codebase-design 是一套面向代码设计或重构的共享词汇与方法原则,核心是设计「深模块」:用小型接口封装大量行为,将接缝放在干净的位置,并通过该接口进行测试。其目标是同时兼顾三方面:为调用方提供杠杆,为维护者提供局部性,并让所有人获得可测试性。
一、术语表 文档要求严格使用以下术语,不用“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:维护者从深度中获得的东西,变更、缺陷、知识和验证集中在一处而非分散到各调用方;一处修复,处处修复。
二、深与浅 深模块 = 小接口 + 大量实现:接口方法少、参数简单,复杂逻辑被隐藏。浅模块 = 大接口 + 少量实现(应避免):方法多、参数复杂,实现只是透传。设计接口时应自问:能否减少方法数量?能否简化参数?能否在内部隐藏更多复杂度?
三、原则
- 深度是接口的属性,不是实现的属性。深模块内部可以由小型、可模拟、可替换的部件组成,只是它们不属于接口。模块可以有内部接缝(对其实现私有,供自身测试使用)以及接口处的外部接缝。
- 删除测试:想象删除该模块。如果复杂度消失,它只是透传;如果复杂度在 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 讲述探索替代接口,即启动并行子代理以几种截然不同的方式设计接口,再从深度、局部性和接缝位置上进行比较。
限制与未提供信息:该页面未说明具体价格、收费、平台或运行要求,也未提供安装命令或代码仓库使用步骤;这些内容暂未提供。