codebase-design

代码库设计

设计深模块（deep module）：小接口背后藏大量行为，安放在干净的接缝（seam）处，可通过该接口测试。凡是在设计或重构代码之处，都使用这套语言和这些原则。目标是给调用方杠杆（leverage），给维护者局部性（locality），给所有人可测试性。

术语表

精确使用这些术语：不要换成"component""service""API"或"boundary"。语言保持一致正是全部意义所在。

模块（Module）：任何拥有接口和实现的东西。刻意不区分规模：函数、类、包，或跨层的垂直切片（vertical slice）。避免：unit、component、service。

接口（Interface）：调用方要正确使用该模块必须知道的一切：类型签名，以及不变量、顺序约束、错误模式、必需的配置和性能特征。避免：API、signature（太窄，它们只指类型层面的表面）。

实现（Implementation）：模块内部的东西，它的代码本体。与**适配器（adapter）**相区别：一个东西可以是带大实现的小适配器（Postgres 仓储），也可以是带小实现的大适配器（内存 fake）。话题是接缝时用"adapter"，否则用"implementation"。

深度（Depth）：接口处的杠杆。调用方（或测试）每学习一单位接口所能调用的行为量。大量行为位于小接口之后时，模块是深的（deep）；接口几乎与实现一样复杂时，是浅的（shallow）。

接缝（Seam）（Michael Feathers）：无需在原地编辑即可改变行为的地方；模块接口所处的位置。接缝放在哪里，本身就是一个独立的设计决策，与它背后放什么无关。避免：boundary（与 DDD 的 bounded context 含义过载）。

适配器（Adapter）：在接缝处满足某个接口的具体事物。描述的是角色（填补哪个槽位），而非实体（内部是什么）。

杠杆（Leverage）：调用方从深度中获得的东西。每学习一单位接口，换来更多能力。一个实现可在 N 个调用点和 M 个测试中获得回报。

局部性（Locality）：维护者从深度中获得的东西。变更、bug、知识和验证集中在一处，而不是散布到各调用方。修一次，处处修好。

深与浅

深模块 = 小接口 + 大量实现：

┌─────────────────────┐
│   Small Interface   │  ← Few methods, simple params
├─────────────────────┤
│                     │
│  Deep Implementation│  ← Complex logic hidden
│                     │
└─────────────────────┘

浅模块 = 大接口 + 少量实现（应避免）：

┌─────────────────────────────────┐
│       Large Interface           │  ← Many methods, complex params
├─────────────────────────────────┤
│  Thin Implementation            │  ← Just passes through
└─────────────────────────────────┘

设计接口时，问自己：

• 能减少方法数量吗？
• 能简化参数吗？
• 能在内部藏起更多复杂度吗？

原则

• 深度是接口的属性，不是实现的属性。 深模块内部可以由小的、可 mock、可替换的部件组成；只是它们不属于接口。模块除了接口处的外部接缝，还可以有内部接缝（私有于其实现，供它自己的测试使用）。
• 删除测试（deletion test）。 想象删掉这个模块。如果复杂度随之消失，它就只是个直通层。如果复杂度在 N 个调用方身上重现，说明它物有所值。
• 接口就是测试面。 调用方和测试穿越的是同一道接缝。如果你想越过接口去测，这个模块的形状多半不对。
• 一个适配器意味着假想接缝。两个适配器才意味着真接缝。 除非真有东西跨接缝变化，否则不要引入接缝。

为可测试性设计

好的接口让测试自然而然：

1. 接受依赖，不要创建依赖。

   // Testable
   function processOrder(order, paymentGateway) {}
   
   // Hard to test
   function processOrder(order) {
     const gateway = new StripeGateway();
   }