system-design

软件架构开发技能

此技能为注重质量的软件开发与架构设计提供指导，基于整洁架构和领域驱动设计原则。

代码风格规则

通用原则

• 提前返回模式：尽可能始终使用提前返回，而不是嵌套条件，以提高可读性
• 通过创建可复用的函数和模块避免代码重复
• 将较长（超过 80 行代码）的组件和函数拆分为多个较小的组件和函数。如果它们无法在其他地方复用，就保留在同一文件中。但如果文件超过 200 行代码，则应拆分为多个文件。
• 尽可能使用箭头函数，而不是函数声明

最佳实践

库优先方法

• 编写自定义代码前，务必先搜索现有解决方案
  • 检查 npm 上是否有解决问题的现有库
  • 评估现有服务或 SaaS 解决方案
  • 考虑用于常见功能的第三方 API
• 使用库，而不是编写自己的工具函数或辅助函数。例如，使用 cockatiel，而不是自行编写重试逻辑。
• 适合编写自定义代码的情况：
  • 领域特有的业务逻辑
  • 有特殊要求的性能关键路径
  • 外部依赖过于繁重的情况
  • 需要完全掌控的安全敏感代码
  • 经过全面评估后，现有解决方案仍无法满足需求

架构与设计

• 整洁架构与 DDD 原则：
  • 遵循领域驱动设计和通用语言
  • 将领域实体与基础设施关注点分离
  • 让业务逻辑不依赖框架
  • 明确定义用例并保持隔离
• 命名约定：
  • 避免使用通用名称：utils、helpers、common、shared
  • 使用领域特定名称：OrderCalculator、UserAuthenticator、InvoiceGenerator
  • 遵循限界上下文的命名模式
  • 每个模块都应有单一且明确的用途
• 关注点分离：
  • 不要将业务逻辑与 UI 组件混在一起
  • 不要在控制器中编写数据库查询
  • 在各上下文之间保持清晰的边界
  • 确保职责得到适当分离

应避免的反模式

• NIH（非我发明综合征）：
  • Auth0/Supabase 已提供身份验证时，不要自行构建身份验证功能
  • 不要自行编写状态管理，而应使用 Redux/Zustand
  • 不要自行创建表单验证功能，而应使用成熟的库
• 糟糕的架构选择：
  • 将业务逻辑与 UI 组件混在一起
  • 直接在控制器中编写数据库查询
  • 缺乏清晰的关注点分离
• 通用命名反模式：
  • 包含 50 个无关函数的 utils.js
  • 作为杂项堆放处的 helpers/misc.js
  • 用途不明的 common/shared.js
• 请记住：每一行自定义代码都意味着维护、测试和文档方面的负担
• 错误处理要规范，并为 catch 块指定类型
• 将复杂逻辑拆分为更小、可复用的函数
• 避免深层嵌套（最多 3 层）
• 尽可能让函数职责单一且少于 50 行
• 尽可能让文件职责单一且少于 200 行代码