kscz0000 软件架构开发技能
本技能提供面向质量的软件开发与架构指导，基于 Clean Architecture 和领域驱动设计（DDD）原则。
代码风格规范
通用原则
- 提前返回模式：尽可能使用提前返回代替嵌套条件，以提升可读性
- 通过创建可复用的函数和模块避免代码重复
- 将过长的组件和函数（超过 80 行代码）拆分为多个更小的组件和函数。如果无法在其他地方复用，保留在同一文件中。但如果文件超过 200 行代码，应拆分为多个文件
- 尽可能使用箭头函数代替函数声明
最佳实践
优先使用现有库
- 在编写自定义代码之前，务必先搜索现有解决方案
- 在 npm 中查找已有的库来解决问题
- 评估现有的服务/SaaS 方案
- 考虑使用第三方 API 实现通用功能
- 使用现有库而不是自己编写工具函数。例如，使用
cockatiel而不是自己编写重试逻辑。 - 以下情况可以编写自定义代码：
- 领域特有的业务逻辑
- 有特殊要求的性能关键路径
- 外部依赖过于笨重时
- 需要完全控制的安全敏感代码
- 经过充分评估后现有方案均不满足需求
架构与设计
- Clean Architecture 与 DDD 原则：
- 遵循领域驱动设计和统一语言
- 将领域实体与基础设施关注点分离
- 保持业务逻辑独立于框架
- 清晰定义用例并保持隔离
- 命名规范：
- 避免通用命名：
utils、helpers、common、shared - 使用领域特定命名：
OrderCalculator、UserAuthenticator、InvoiceGenerator - 遵循限界上下文命名模式
- 每个模块应有单一且明确的职责
- 避免通用命名：
- 关注点分离：
- 不要将业务逻辑与 UI 组件混在一起
- 不要在控制器中编写数据库查询
- 维护上下文之间的清晰边界
- 确保职责的合理分离
需要避免的反模式
- NIH（非我发明）综合征：
- 不要在 Auth0/Supabase 存在的情况下自建认证系统
- 不要在 Redux/Zustand 可用的情况下自写状态管理
- 不要在成熟库可用的情况下自创表单验证
- 糟糕的架构选择：
- 将业务逻辑与 UI 组件混在一起
- 在控制器中直接写数据库查询
- 缺乏清晰的关注点分离
- 通用命名反模式：
utils.js里放了 50 个不相关的函数helpers/misc.js成了万能垃圾桶common/shared.js职责不明确
- 请记住：每一行自定义代码都是需要维护、测试和文档化的负债
代码质量
- 使用类型化的 catch 块进行恰当的错误处理
- 将复杂逻辑拆分为更小的可复用函数
- 避免深层嵌套（最多 3 层）
- 保持函数聚焦，尽量控制在 50 行以内
- 保持文件聚焦，尽量控制在 200 行代码以内
适用场景
本技能适用于执行概述中描述的工作流程或操作。
局限性
- 仅在任务明确匹配上述范围时使用本技能。
- 不要将输出视为环境特定验证、测试或专家评审的替代品。
- 如果缺少必要的输入、权限、安全边界或成功标准，请停下来请求澄清。