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 行代码

何时使用

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

示例

用户请求：

使用 @software-architecture 完成此任务：注重质量的软件架构指南。

限制

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