SuperAPI AI 工具集

codebase-design

编程与开发

查看项目

更新于 11-04 04:19

技能介绍

用途

本技能提供一套用于设计和重构代码时统一使用的词汇与原则,聚焦于“深模块”设计:以小接口承载大量行为,将模块放在清晰的接缝处,并可通过该接口进行测试。适用于任何正在设计或重构代码的场景。技能以“提示词或简述点名该技能”作为调用方式。

术语表(需严格使用以下术语,不要替换为 component、service、API、boundary)

  • Module(模块):任何拥有接口和实现的东西,刻意与规模无关,可以是函数、类、包或跨层切片。避免使用 unit、component、service。
  • Interface(接口):调用者正确使用模块必须知道的一切,包括类型签名,也包括不变量、顺序约束、错误模式、必需配置和性能特征。避免使用 API、signature(过窄,仅指类型层面)。
  • Implementation(实现):模块内部、其代码主体。与 Adapter 区分:小的适配器也可能有大实现(如 Postgres 仓储),大的适配器也可能有小实现(如内存假实现)。当议题是接缝时用 adapter,否则用 implementation。
  • Depth(深度):接口处的杠杆。调用者(或测试)每学习一单位接口所能使用的行为量。行为多而接口小为深,接口复杂度接近实现为浅。
  • Seam(接缝,Michael Feathers):无需在该处编辑即可改变行为的位置;模块接口所在之处。接缝放哪里是独立的设计决策,与接缝后面放什么不同。避免使用 boundary(与 DDD 的限界上下文混淆)。
  • Adapter(适配器):在接缝处满足接口的具体事物,描述角色(填哪个槽)而非实质(内部是什么)。
  • Leverage(杠杆):调用者从深度中获得的东西,每单位接口提供更多能力,一份实现回报 N 个调用点和 M 个测试。
  • Locality(局部性):维护者从深度中获得的东西,变更、缺陷、知识和验证集中在一处而非散落于调用者。修一次,处处修好。

深与浅

  • 深模块 = 小接口 + 大量实现:方法少、参数简单,隐藏复杂逻辑。
  • 浅模块 = 大接口 + 少量实现(应避免):方法多、参数复杂,仅做透传。 设计接口时可自问:能否减少方法数量?能否简化参数?能否在内部隐藏更多复杂度?

原则

  • 深度是接口的属性,而非实现的属性。深模块内部可以由小的、可 mock、可替换的部件组成,只是它们不属于接口。模块可以有内部接缝(对实现私有、供自身测试使用)以及接口处的外部接缝。
  • 删除测试:设想删除该模块。若复杂度消失,说明它只是透传;若复杂度在 N 个调用者处重新出现,说明它物有所值。
  • 接口即测试面:调用者和测试跨越同一接缝。若想绕过接口测试,模块形态多半不对。
  • 一个适配器意味着假设的接缝,两个适配器意味着真实的接缝。除非确有东西沿接缝变化,否则不要引入接缝。

为可测试性而设计

良好接口让测试自然:

  • 接受依赖,不要创建依赖。示例:可测试为 function processOrder(order, paymentGateway) {};难测试为 function processOrder(order) { const gateway = new StripeGateway(); }。
  • 返回结果,不要产生副作用。示例:可测试为 function calculateDiscount(cart): Discount {};难测试为 function applyDiscount(cart): void { cart.total -= discount; }。
  • 缩小表面积:方法越少,所需测试越少;参数越少,测试准备越简单。

关系

  • 一个 Module 恰好有一个 Interface(呈现给调用者和测试的面)。
  • Depth 是 Module 的属性,相对其 Interface 衡量。
  • Seam 是 Module 的 Interface 所在之处。
  • Adapter 位于 Seam 处并满足 Interface。
  • Depth 为调用者产生 Leverage,为维护者产生 Locality。

被拒绝的框架

  • 将深度视为实现行数与接口行数之比(Ousterhout):会奖励对实现注水。本技能改用深度即杠杆。
  • 将 Interface 理解为 TypeScript 的 interface 关键字或类的公开方法:过窄;此处的接口包含调用者必须知道的一切事实。
  • “Boundary”:与 DDD 的限界上下文混淆,应说 seam 或 interface。

深入阅读

  • 给定依赖加深一簇模块,见 DEEPENING.md:依赖类别、接缝纪律、替换而非分层的测试。
  • 探索替代接口,见 DESIGN-IT-TWICE.md:启动并行的子代理,以几种截然不同的方式设计接口,再从深度、局部性和接缝位置进行比较。
  • 读取文件路径相对于仓库根目录。GLOSSARY.md 是项目领域语言,Design It Twice 会将其传给每个子代理;若缺失,只传本技能的词汇。