SuperAPI AI 工具集

software-architecture

编程与开发

查看项目

更新于 11-11 16:18

技能介绍

用途

该技能为注重质量的软件开发与架构提供指导,基于整洁架构(Clean Architecture)和领域驱动设计(Domain Driven Design)原则。当用户需要编写代码、设计架构、分析代码,或遇到其他匹配上述范围的场景时,可使用本技能。

代码风格规则

通用原则:

  • 提前返回:尽可能使用提前返回模式,而非嵌套条件,以提升可读性。
  • 避免代码重复:通过创建可复用的函数和模块来减少重复。
  • 拆分过长组件与函数:将超过 80 行的组件和函数拆分为更小的组件和函数;若无法在其他地方复用,可保留在同一文件中,但文件超过 200 行代码时应拆分为多个文件。
  • 优先使用箭头函数而非函数声明(在可能的情况下)。

最佳实践:库优先

始终在编写自定义代码前搜索现有解决方案:

  • 检查 npm 中是否有解决该问题的现有库。
  • 评估现有服务或 SaaS 方案。
  • 考虑为常见功能使用第三方 API。
  • 使用库而非自写工具或辅助函数,例如使用 cockatiel 而非自行编写重试逻辑。

仅在以下情况自写代码是合理的:

  • 领域特有的业务逻辑。
  • 有特殊要求的性能关键路径。
  • 外部依赖过于笨重时。
  • 需要完全控制的安全敏感代码。
  • 经过充分评估后现有方案仍不满足需求时。

架构与设计

整洁架构与 DDD 原则:

  • 遵循领域驱动设计与统一语言(ubiquitous language)。
  • 将领域实体与基础设施关注点分离。
  • 保持业务逻辑独立于框架。
  • 清晰定义用例并保持其隔离。

命名约定:

  • 避免通用名称:utils、helpers、common、shared。
  • 使用领域专用名称:OrderCalculator、UserAuthenticator、InvoiceGenerator。
  • 遵循限界上下文命名模式。
  • 每个模块应有单一、明确的目的。

关注点分离:

  • 不要将业务逻辑与 UI 组件混在一起。
  • 不要在控制器中直接进行数据库查询。
  • 保持上下文之间的清晰边界。
  • 确保职责的恰当分离。

需避免的反模式

NIH(Not Invented Here)综合征:

  • 已有 Auth0/Supabase 时不要自建认证。
  • 不要自写状态管理而不用 Redux/Zustand。
  • 不要自写表单校验而不用成熟库。

不佳的架构选择:

  • 业务逻辑与 UI 组件混用。
  • 控制器中直接进行数据库查询。
  • 缺乏清晰的关注点分离。

通用命名反模式:

  • utils.js 中塞入 50 个互不相关的函数。
  • helpers/misc.js 作为杂物堆放地。
  • common/shared.js 目的不明。

请记住:每一行自定义代码都是需要维护、测试和文档化的负债。

代码质量

  • 使用带类型的 catch 块进行恰当的错误处理。
  • 将复杂逻辑拆分为更小、可复用的函数。
  • 避免深层嵌套(最多 3 层)。
  • 函数保持聚焦,尽量在 50 行以内。
  • 文件保持聚焦,尽量在 200 行代码以内。

适用场景

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

限制

  • 仅在任务明确匹配上述范围时使用本技能。
  • 不要将输出视为针对具体环境的验证、测试或专家评审的替代品。
  • 缺少必要输入、权限、安全边界或成功标准时,应停止并请求澄清。