软件架构开发技能Skill software-architecture

---

名称: 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行代码以内