用途:在设计与重构代码时,用统一词汇描述模块的接口与实现,目标是设计“深模块”——大量行为藏在很小接口之后,放在干净的接缝处,并能通过该接口测试。
术语(需严格使用,不要用 component、service、API、boundary 替代):模块 Module:带接口与实现的任何东西,刻意与规模无关,函数、类、包或跨层切片皆可。接口 Interface:调用方正确使用模块所需知道的一切,包括类型签名、不变量、顺序约束、错误模式、必需配置与性能特征。实现 Implementation:模块内部代码,与 Adapter 区分:小适配器可有大实现(如 Postgres 仓库),大适配器可有小实现(如内存假实现)。深度 Depth:接口处的杠杆,即调用方或测试每学一单位接口能触达的行为量;行为多而接口小为深,接口复杂度接近实现为浅。接缝 Seam:可在此处改变行为而无需编辑该处,是接口所在位置,属独立设计决策。适配器 Adapter:在接缝处满足接口的具体物,描述角色而非内容。杠杆 Leverage:调用方从深度所得。局部性 Locality:维护者从深度所得,变更、缺陷、知识与验证集中一处。
主要能力与原则:设计接口时问能否减少方法数、简化参数、隐藏更多复杂度。深度是接口属性而非实现属性;深模块内部可由小、可 mock、可替换的部分组成,只是不进入接口,也可有供自身测试使用的内部接缝。删除测试:删除该模块后若复杂度消失,说明它只是透传;若复杂度在 N 个调用方重新出现,则它在创造价值。接口即测试面:调用方与测试跨越同一接缝,若想越过接口测试,模块形状可能不对。一个适配器只是假设接缝,两个适配器才是真实接缝;没有真正变化就不要引入接缝。为可测试性设计:接受依赖而非创建依赖;返回结果而非产生副作用;保持小接口面。
关系:一个模块恰有一个接口;深度相对接口衡量;接缝是接口所在处;适配器位于接缝并满足接口;深度为调用方产生杠杆、为维护者产生局部性。
被否定的框架:不以实现行数与接口行数之比衡量深度(会鼓励填充实现),改用深度即杠杆;不把接口窄化为 TypeScript 的 interface 关键字或类的公开方法;不用 boundary 一词,改说接缝或接口。
延伸:给定依赖深化一组模块见 DEEPENING.md;探索替代接口见 DESIGN-IT-TWICE.md。具体安装或使用命令资料未提供。