SuperAPI AI 工具集

software-design-principles

编程与开发

查看项目

更新于 10-16 17:13

技能介绍

用途

这套技能是“代码层面的工程准则”(The code-level engineering canon),用于在架构评审、方案规划与重构阶段提供统一的代码设计判断依据。资料明确说明:它仅有 Markdown,不含脚本,属于被查阅(consulted)而非被调用(invoked)的资料;工作流类技能会引用它,智能体与人类都会阅读。更大范围的主题由同级技能承担:系统层面的 architectural-design-principles,以及体验层面的 ui-ux-design-principles。

主要能力

1. 架构关注点映射(提升/合并前必做)

资料要求在宣布设计完成前,为任何非平凡变更填写关注点映射,包含四列:关注点、层次、归属模块、是否横切。示例行包括:

  • 认证(Authentication):HTTP / 边界,横切为“是”
  • 授权(Authorization):Service,横切为“是”
  • 能力解析(Capability resolution):Service,横切为“是”
  • 审计日志(Audit logging):横切,横切为“是”
  • 限流(Rate limiting):HTTP / 边界,横切为“是”
  • 模式校验(Schema validation):HTTP / 边界,横切为“是”
  • 策略配置(Policy config):Service / config,横切为“是”
  • 领域逻辑(Domain logic):Service,横切为“否”
  • 存储(Storage):Infrastructure,横切为“否”

资料指出:留空的行,或没有明确归属者的关注点,都是设计坏味道,应在合并前解决。

2. 引用的参考主题

资料列出以下参考主题:SOLID(五条对象设计规则)、DRY(每段逻辑只有一处归属)、整洁代码(命名、函数形态、注释、错误边界)、横切关注点(认证、授权、能力解析、审计、限流、模式、策略各由哪一层拥有)、NFR(性能、可扩展性、安全、可观测性、可运维性、韧性)。分层架构则位于架构类技能中(作为参考)。

使用方式

作为被引用文档使用。资料写明组合方式:consort – Architect Reviewer 在逐故事评审中引用它;Navigator 在 PLAN 阶段使用;Driver 在 REFACTOR 阶段使用。lakebase-scm-workflows 则用于按分层架构与横切检查来评审 PR。也就是说,它本身不提供脚本或安装命令,而是供这些工作流在相应阶段查阅。

硬性规则

资料给出的硬性规则包括:

  • 命名承载设计。新读者若无法从名称推断概念,应在下一次测试前重命名。
  • 层次向内依赖。HTTP -> service -> infrastructure,绝不反向。
  • 每个横切关注点只有一个归属者。两个模块中重叠的认证/审计逻辑是坏味道:一个拥有,其余委托。
  • 不重复逻辑。写代码块前先找是否已有副本并抽出一处共享辅助;修复 bug 时一并修好所有调用点。
  • 完成前检查 NFR 基线:浏览性能、可扩展性、安全、可观测性、可运维性、韧性。
  • 公共边界测试、私有重构。正确的重构绝不改变外层边界测试。
  • 导入期不得耦合可选构建产物。模块必须在其发布的所有环境中都能导入;在导入作用域无条件挂载 StaticFiles 或读取资源,会在产物存在处通过、在不存在处崩溃(仅后端测试、客户端构建前的 CI、全新克隆)。仅在存在时挂载/读取,不存在时明确降级(503 “not built”)。该坏味道由 consort-imports-clean 强制。
  • 测试在某一时点编码需求,演进可以取代它们。需求累积,最新者胜。当后续 AC、故事或功能有意改变早先测试断言的行为(删除列、变更契约、移除端点、重命名字段),该早先测试即被取代:它既不是回归,也不是需要保留的约束。应随使其过时的那次变更一起,把该测试重构为新行为或将其退役,跨故事与功能,而不只是当前手头这一个;绝不可削弱测试或强行变绿来保活已过时的断言。真正的回归相反(仍然有效的行为被意外破坏:修代码、保留测试)。区分取代与回归是必要的判断,不是停下的理由;只有真实冲突(让被取代的测试变为当前会破坏某个仍然有效的测试)才升级处理。扫描取代要全面,不能只看命名了变更形状的测试:当变更删除/重命名列、字段、表或端点时,被取代集合还包括断言已消失形状属性的 FITNESS / 架构 / 迁移测试,例如可逆性检查(“up() 后 down(),列被重建”)、模式形状断言(“该列存在”)、旧字段上的不变量。为后续契约步骤有意删除的列编写的可逆性/适应性测试,编码的是已废弃行为,与其他测试一样被取代。漏掉一个会让测试套件因变更完全有意为之的原因而变红。
  • 模式契约变更要同步更新数据模型与代码。删除列(或移除/重命名字段、表、端点)不是在写好迁移时就完成了。在同一次变更中,还必须从 ORM/模型定义、每个提到它的查询、每个序列化器/DTO、每个模板/视图中移除它,否则运行中的代码仍会为数据库已不存在的东西发出 SQL(或响应),即使迁移“成功”也会在运行时出现 column ... does not exist。迁移改变数据库;模型 + 查询 + 视图必须与之匹配。这是 expand/contract 的契约一半:expand 添加新形状并回填;contract 在所有地方移除旧形状(数据库与代码一起),绝不只是数据库。

适用场景与限制

适用场景:代码设计评审、方案规划、重构、PR 评审,尤其是涉及横切关注点归属、层次依赖、NFR 基线、测试取代判定与模式契约变更的变更。资料提到它被 consort(Architect Reviewer、Navigator、Driver)与 lakebase-scm-workflows 使用。

限制:资料明确其为 Markdown-only、无脚本,不被调用而只被查阅;系统级分层架构与体验级设计分别位于 architectural-design-principles 与 ui-ux-design-principles 这两个同级技能,不在此覆盖。资料未提供安装命令、价格、收费、平台支持、效果数据或具体使用步骤等信息。