codebase-design

Vendored from mattpocock/skills · MIT © 2026 Matt Pocock · upstream 6eeb81b · 已汉化并完成 VoidTech 插件内自包含适配。LICENSE 见 ../_vendor-licenses/mattpocock-LICENSE

代码库设计

设计 deep module（深模块）：用简单接口提供完整能力，把实现细节留在清晰的 seam（可替换接缝）之后，并通过公开接口测试行为。目标是让调用方用更少的接口获得更多能力，让修改和排错集中在模块内部。

术语表

统一使用以下术语，不要用含义不完全相同的 "component"、"service"、"API" 或 "boundary" 替换。

Module（模块） — 任何同时具有接口和实现的代码单元，可以是函数、类、包或跨层切片。避免：unit、component、service。

Interface（接口） — 调用方为了正确使用模块而必须知道的一切，包括类型签名、不变式、调用顺序、错误方式、必要配置和性能特征。避免：API、signature（只表达了类型层面的表面）。

Implementation（实现） — 模块内部代码。它与 Adapter 不同：adapter 描述代码在 seam 处承担的角色，implementation 描述模块内部如何工作。讨论 seam 时使用 "adapter"，其他情况使用 "implementation"。

Depth（深度） — 简单接口背后包含的有效能力。接口小、内部能力完整的是 deep（深） 模块；接口与实现同样复杂的是 shallow（浅） 模块。

Seam（可替换接缝） (Michael Feathers) — 无需修改调用方，就能替换实现或改变行为的位置。seam 通常位于模块接口处；放在哪里与背后采用什么实现是两个不同决策。避免：boundary（容易与 DDD 的 bounded context 混淆）。

Adapter（适配器） — 在某个 seam 处实现接口的对象或模块。这个词描述它承担的角色，而不是内部实现方式。

Leverage（接口收益） — 调用方只需理解少量接口，就能使用较多能力。同一份实现可以服务多个调用点和测试。

Locality（修改集中度） — 变更、缺陷、业务知识和验证逻辑集中在模块内部，而不是散落到多个调用方。一处修复即可覆盖所有调用点。

深模块与浅模块

Deep module = 小接口 + 大量实现：

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

Shallow module = 大接口 + 少量实现（避免）：

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

设计接口时，问自己：

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

原则

• Depth 是接口的属性，不是实现的属性。 深模块内部可以由小型、可 mock、可替换的部件组成，但这些部件不需要暴露为公开接口。模块可以有私有的 internal seams（内部 seam），也可以在公开接口处有 external seam（外部 seam）。
• 移除模块检验。 设想删掉该模块。如果复杂度也随之消失，它可能只是简单转发；如果复杂度会在多个调用方重复出现，这个模块就在承担有效职责。
• 接口就是测试面。 调用方和测试都应通过同一个 seam 使用模块。如果测试必须绕过接口，模块边界可能设计得不合适。
• 只有一个适配器时，seam 可能只是过度设计；出现两个适配器时，seam 才有明确价值。 只有确实需要替换实现时才引入 seam。