SuperAPI AI 工具集

codebase-design

编程与开发

查看项目

更新于 11-07 16:46

技能介绍

用途

codebase-design 是一套用于“设计深模块”的共享词汇和设计原则。资料说明,深模块指“大量行为藏在小接口之后,放在清晰的接缝处,并能通过该接口进行测试”。该技能的目标是:为调用方提供杠杆,为维护者提供局部性,为所有人提供可测试性。它用于任何正在设计或重构代码的场合,帮助团队用一致的语言讨论模块形状、接口边界和接缝位置。

主要能力与术语

资料要求严格使用以下术语,不要用 component、service、API、boundary 替代:

  • 模块(Module):任何具有接口和实现的东西,刻意不限定尺度,可以是函数、类、包或跨层切片。避免说 unit、component、service。
  • 接口(Interface):调用方正确使用模块所必须知道的一切,包括类型签名,也包括不变量、顺序约束、错误模式、必需配置和性能特征。避免说 API、signature,因为它们太窄,只指类型层面的表面。
  • 实现(Implementation):模块内部的东西、代码主体。与适配器区分:小适配器可以有大实现(如 Postgres 仓库),大适配器也可以有小实现(如内存假实现)。讨论接缝时用“适配器”,否则用“实现”。
  • 深度(Depth):接口处的杠杆,即调用方或测试每学习一单位接口所能触发的行为量。大量行为藏在小接口后就是深,接口几乎和实现一样复杂就是浅。
  • 接缝(Seam,Michael Feathers):可以在不编辑该处的情况下改变行为的地方;模块接口所在的位置。接缝放在哪里是独立的设计决策,与接缝后面放什么不同。避免说 boundary,因为该词与 DDD 的限界上下文重载。
  • 适配器(Adapter):在接缝处满足接口的具体事物,描述角色(填哪个槽),而非实质(里面是什么)。
  • 杠杆(Leverage):调用方从深度中获得的东西,每学习一单位接口获得更多能力;一份实现可在 N 个调用点和 M 个测试中回本。
  • 局部性(Locality):维护者从深度中获得的东西,变更、缺陷、知识和验证集中在一处,而非散布到调用方;修一次,处处修好。

深模块与浅模块

资料用图示区分:深模块 = 小接口 + 大量实现,接口方法少、参数简单,复杂逻辑被隐藏;浅模块 = 大接口 + 少量实现,应避免,接口方法多、参数复杂,实现只是透传。设计接口时建议自问:能否减少方法数量?能否简化参数?能否把更多复杂度藏到内部?

使用原则

  • 深度是接口的属性,不是实现的属性。深模块内部可以由小而可 mock、可替换的部分组成,只是它们不属于接口。模块可以有内部接缝(实现私有,供自身测试使用)以及接口处的外部接缝。
  • 删除测试:想象删除该模块。如果复杂度消失,它只是透传;如果复杂度在 N 个调用方处重新出现,它就在发挥作用。
  • 接口即测试面:调用方和测试穿过同一个接缝。如果想越过接口去测试,模块形状很可能不对。
  • 一个适配器意味着假设的接缝,两个适配器才意味着真实的接缝。除非确实有东西在接缝处变化,否则不要引入接缝。

按可测试性设计

好的接口让测试自然:接受依赖,不要创建依赖(示例:processOrder(order, paymentGateway) 可测试,而内部 new StripeGateway() 难以测试);返回结果,不要产生副作用(示例:calculateDiscount(cart): Discount 可测试,而 applyDiscount(cart): void 难以测试);缩小表面积,方法越少需要测试越少,参数越少测试准备越简单。

概念关系

一个模块恰好有一个接口(呈现给调用方和测试的表面);深度是模块相对于其接口的属性;接缝是模块接口所在之处;适配器位于接缝处并满足接口;深度为调用方产生杠杆、为维护者产生局部性。

拒绝的框架

资料明确拒绝三种用法:不用“实现行数与接口行数之比”定义深度(Ousterhout 式),因为那会奖励填充实现;不把“接口”窄化为 TypeScript 的 interface 关键字或类的公开方法,因为这里的接口包含调用方必须知道的一切事实;不用“boundary”,因为它与 DDD 的限界上下文重载,应说接缝或接口。

深入内容

资料提到进一步阅读:给定依赖时深化一组模块,见 DEEPENING.md,涉及依赖类别、接缝纪律和“替换而非分层”的测试;探索替代接口,见 DESIGN-IT-TWICE.md,即启动并行子代理以几种截然不同的方式设计接口,然后按深度、局部性和接缝位置比较。

适用场景与限制

该技能适合在设计和重构模块接口、寻找深化机会、决定接缝位置、讨论代码结构时作为共同语言和判断标准。资料未提供具体安装方式、命令、收费、价格、平台或运行环境信息,这些暂未提供。