用途:在任何设计或重构代码的场景中使用这套语言与原则,目标是设计 deep modules,即把大量行为放在小 interface 之后,把 interface 放在清晰 seam 上,并通过该 interface 测试。它为 callers 带来 leverage,为 maintainers 带来 locality,让代码更易测试。
术语表:Module 指任何拥有 interface 和 implementation 的东西,不限定尺度,function、class、package 或跨层 slice 均可。Interface 指 caller 为正确使用 module 必须知道的一切,包括 type signature、invariants、ordering constraints、error modes、required configuration 和 performance characteristics。Implementation 指 module 内部代码体;讨论 seam 时说 adapter,其他时候说 implementation。Depth 是 interface 上的 leverage:行为藏在小 interface 后面为 deep,interface 几乎和 implementation 一样复杂为 shallow。Seam 是可改变行为而不编辑当前位置的地方。Adapter 是在 seam 上满足某 interface 的具体东西。
主要能力与原则:Depth 是 interface 的属性而非 implementation 的属性;Deep module 内部可由小的、可 mock、可替换的 parts 组成,但它们不属于 interface。Deletion test:想象删除该 module,若复杂度消失则它只是 pass-through,若复杂度散落到 N 个 callers 则它在发挥价值。Interface 即测试面:callers 和 tests 穿过同一 seam。One adapter means a hypothetical seam. Two adapters means a real one. 没有东西会跨 seam 变化时不要引入 seam。
为可测试性而设计:接受依赖,不要创建依赖;返回结果,不要产生副作用;缩小 surface area,更少 methods 与 params 意味着更少 tests 与更简单 setup。设计 interface 时自问:能减少 methods 数量吗?能简化 parameters 吗?能把更多复杂度藏到内部吗?
限制:不采用把 depth 当作 implementation-lines 与 interface-lines 比例的表述;不把 Interface 窄化为 TypeScript interface 关键字或类 public methods;用 seam 或 interface 而非 boundary。进一步深化见 DEEPENING.md 与 DESIGN-IT-TWICE.md。其余平台与安装信息暂未提供。