devcxl Codebase Design
设计 深度模块（deep modules）：一个小接口背后承载大量行为，放置在干净的 seam 处，通过该接口可测试。在设计和重构代码的任何地方，都使用这套语言和原则。目标是：对调用者而言是杠杆效应（leverage），对维护者而言是局部性（locality），对所有人而言是可测试性。
词汇表
精确使用以下术语 —— 不要替换为"组件"、"服务"、"API"或"边界"。使用一致的语言正是关键所在。
Module（模块） —— 任何具有接口和实现的东西。特意与规模无关：一个函数、类、包或跨层级切片。避免使用：单元、组件、服务。
Interface（接口） —— 调用者正确使用该模块所需知道的一切：类型签名，还包括不变性约束、顺序约束、错误模式、所需配置和性能特征。避免使用：API、签名（过于狭隘 —— 它们仅指类型层面的表面）。
Implementation（实现） —— 模块内部的内容，它的代码主体。与 Adapter（适配器） 不同：某个东西可以是一个小型适配器配大型实现（如 Postgres 仓库），也可以是一个大型适配器配小型实现（如内存中的假实现）。当讨论重点是 seam 时使用"adapter"；否则使用"implementation"。
Depth（深度） —— 接口处的杠杆效应：调用者（或测试）每学习一个单位的接口就能调用的行为量。当一个模块在小型接口背后承载了大量行为时，它是 深的（deep）；当接口几乎和实现一样复杂时，它是 浅的（shallow）。
Seam（接缝） （Michael Feathers） —— 可以在不修改某处的情况下改变行为的位置；模块接口所在的位置。seam 放在哪里本身就是一个设计决策，与它背后放什么不同。避免使用：边界（与 DDD 的限界上下文 overloaded）。
Adapter（适配器） —— 在 seam 处满足接口的具体实现。描述的是角色（它填充什么槽位），而非实质（内部是什么）。
Leverage（杠杆效应） —— 调用者从深度中获得的好处：每学习一个单位的接口就能获得更多能力。一次实现在 N 个调用点和 M 个测试中回报。
Locality（局部性） —— 维护者从深度中获得的好处：变更、缺陷、知识和验证集中在一个地方，而不是分散在调用者之间。一次修复，处处生效。
深 vs 浅
深度模块 = 小接口 + 大量实现：
┌─────────────────────┐
│ 小型接口 │ ← 少量方法，简单参数
├─────────────────────┤
│ │
│ 深度实现 │ ← 隐藏的复杂逻辑
│ │
└─────────────────────┘
浅模块 = 大接口 + 少量实现（避免）：
┌─────────────────────────────────┐
│ 大型接口 │ ← 大量方法，复杂参数
├─────────────────────────────────┤
│ 薄实现 │ ← 仅透传
└─────────────────────────────────┘
设计接口时，问自己：
- 我能减少方法数量吗？
- 我能简化参数吗？
- 我能在内部隐藏更多复杂性吗？
原则
- 深度是接口的属性，而不是实现的属性。 一个深度模块内部可以由小的、可 mock、可替换的部分组成 —— 它们只是不属于接口而已。一个模块可以有 内部 seam（对其实施私有的，由其自身测试使用）以及其接口处的 外部 seam。
- 删除测试。 想象删除这个模块。如果复杂性消失了，它就是一个透传。如果复杂性在 N 个调用者之间重新出现，那么它是有价值的。
- 接口就是测试面。 调用者和测试穿过同一个 seam。如果你想测试越过接口，那模块的形状可能有问题。
- 一个适配器意味着一个假设的 seam。两个适配器意味着一个真实的 seam。 除非有东西实际在 seam 处变化，否则不要引入 seam。
设计可测试性
好的接口让测试变得自然：
接受依赖，不要创建依赖。
// 可测试 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）：奖励填充实现。我们使用深度即杠杆效应（depth-as-leverage）来代替。
- "Interface" 作为 TypeScript 的
interface关键字或类的 public 方法：过于狭隘 —— 这里的 interface 包含调用者必须知道的每一个事实。 - "Boundary"：与 DDD 的限界上下文 overloaded。请说 seam 或 interface。
深入阅读
- 给定依赖关系深化一个集群 —— 见 DEEPENING.md：依赖分类、seam 纪律和替换而非分层测试。
- 探索备选接口 —— 见 DESIGN-IT-TWICE.md：启动并行的子 agent 以多种截然不同的方式设计接口，然后在深度、局部性和 seam 放置方面进行比较。