software-architecture

软件架构开发技能

本技能为以质量为核心的软件开发和架构提供指导。它基于整洁架构和领域驱动设计原则。

代码风格规则

通用原则

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

最佳实践

库优先方法

• 在编写自定义代码之前，始终搜索现有解决方案
  • 在 npm 中查找可解决该问题的现有库
  • 评估现有的服务/SaaS 解决方案
  • 考虑为常见功能使用第三方 API
• 使用库，而不是编写自己的工具函数或辅助函数。例如，使用 cockatiel 而不是编写自己的重试逻辑。
• 当自定义代码确有必要时：
  • 领域特有的具体业务逻辑
  • 具有特殊要求的性能关键路径
  • 当外部依赖过于大材小用时
  • 需要完全控制的安全敏感代码
  • 经过全面评估后现有解决方案仍不满足需求时

架构与设计

• 整洁架构与 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 行代码