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