---

name: software-architecture description: "注重质量的软件架构指南。当用户想要编写代码、设计架构、分析代码，以及任何与软件开发相关的场景时，应使用此技能。" risk: unknown source: community date_added: "2026-02-27"

软件架构开发技能

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

代码风格规则

通用原则

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

适用场景

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

限制

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