codebase-designlisted

# Codebase Design 设计 **deep modules**：在一小片 interface 背后承载大量行为，放置于干净的 seam 处，并可通过该 interface 测试。凡是在设计或重构代码的地方，都使用这套语言和这些原则。目标是：对调用者而言是 leverage，对维护者而言是 locality，对所有人而言是可测试性。 ## Glossary 请精确使用这些术语——不要替换成 "component"、"service"、"API" 或 "boundary"。统一的语言正是这一切的意义所在。 **Module** — 任何同时具备 interface 和 implementation 的东西。刻意与规模无关：一个 function、class、package 或跨层切片。_Avoid_: unit, component, service. **Interface** — 调用者为了正确使用某个 module 而必须知道的一切：类型签名，以及不变量、顺序约束、错误模式、所需配置和性能特性。_Avoid_: API, signature (too narrow — they refer only to the type-level surface). **Implementation** — module 内部的东西，即它的代码主体。与 **Adapter** 不同：一个东西可以是小 adapter 配大 implementation（如 Postgres repo），也可以是大 adapter 配小 implementation（如 in-memory fake）。当讨论的主题是 seam 时用 "adapter"；否则用 "implementation"。 **Depth** — interface 处的 leverage：调用者（或测试）每学习一份 interface 就能执行的行为量。当一个 module 在小型 interface 背后承载大量行为时，它是 **deep** 的；当 interface 几乎和 implementation 一样复杂时，它是 **shallow** 的。 **Seam** _(Michael Feathers)_ — 一个无需就地编辑即可改变行为的地方；也就是 module 的 interface 所存在的位置。seam 放在哪里本身就是独立的设计决策，与它背后放什么无关。_Avoid_: boundary (overloaded with DDD's bounded context). **Adapter** — 在 seam 处满足某个 interface 的具体东西。描述的是 *角色*（它填补了什么位置），而非实质（里面是什么）。 **Leverage** — 调用者从 depth 中获得的东西：每学习一份 interface 就能获得更多能力。一份 implementation 的回报在 N 个调用点和 M 个测试之间摊还。 **Locality** — 维护者从 depth 中获得的东西：变更、bug、知识和验证集中在一处，而不是散布在调用者之间。修一次，处处修复。 ## Deep vs shallow **Deep module** = 小型 interface + 大量 implementation： ``` ┌─────────────────────┐ │ 小型 Interface │ ← 很少的方法，简单的参数 ├──────