software-architecture

软件架构开发技能

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

代码风格规则

通用原则

• 提前返回模式：尽可能使用提前返回，而不是嵌套条件，以提高可读性
• 通过创建可复用的函数和模块避免代码重复
• 将长（超过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行代码以内

使用时机

本技能适用于执行概述中描述的工作流程或操作。

限制

• 仅当任务明确符合上述范围时使用此技能。
• 不要将输出视为环境特定验证、测试或专家评审的替代品。
• 如果缺少所需的输入、权限、安全边界或成功标准，请停下来寻求澄清。