---
name: codebase-design
description: 设计深度模块的共享词汇。当用户想要设计或改进模块的接口、寻找深化机会、决定 seam 的位置、让代码更可测试或更易被 AI 导航，或者其他 skill 需要深度模块词汇时使用。
---

# 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。

## 设计可测试性

好的接口让测试变得自然：

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

   ```typescript
   // 可测试
   function processOrder(order, paymentGateway) {}

   // 难以测试
   function processOrder(order) {
     const gateway = new StripeGateway();
   }
   ```

2. **返回结果，不要产生副作用。**

   ```typescript
   // 可测试
   function calculateDiscount(cart): Discount {}

   // 难以测试
   function applyDiscount(cart): void {
     cart.total -= discount;
   }
   ```

3. **小表面积。** 方法越少 = 需要的测试越少。参数越少 = 测试设置越简单。

## 关系

- **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](DEEPENING.md)：依赖分类、seam 纪律和替换而非分层测试。
- **探索备选接口** —— 见 [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md)：启动并行的子 agent 以多种截然不同的方式设计接口，然后在深度、局部性和 seam 放置方面进行比较。