deep-module-design-zh

深模块设计、模块接口设计、接缝（seam）放在哪、可测试性设计、找加深机会、设计两次。当用户说「这个模块接口怎么设计」「代码太碎了怎么合并成深模块」「接缝放哪」「怎么让代码更好测」「帮我设计几种不同的接口方案比较」「什么是深模块」时使用。 统一词汇： - 模块：封装特定功能的代码单元 - 接口：模块对外暴露的调用方式（函数签名、参数、返回值） - 实现：模块内部的具体逻辑 - 深度：接口的抽象程度与功能集中度的综合体现（接口越简洁、功能越集中，模块越深） - 接缝（seam）：可替换依赖的接入点，用于测试或扩展 - 适配器：将外部依赖或内部实现适配到模块接口的中间层 - 杠杆：通过小改动带来大收益的设计点（如接缝位置、接口抽象） - 局部性：相关逻辑是否集中，调用方是否需了解过多内部细节 深模块 vs 浅模块： - 深模块：接口简洁、功能集中、隐藏复杂实现，调用方无需了解内部细节（高杠杆） - 浅模块：接口复杂、功能分散、暴露过多实现细节，调用方需了解内部逻辑（低杠杆） 核心原则： - 深度是接口的属性：模块的深度取决于其接口设计，而非实现复杂度 - 删除测试：若一个模块无法被有效测试，说明其接口设计有问题 - 接口即测试面：接口是测试的主要入口，接口越清晰，测试越容易 - 一个适配器是假接缝，两个才是真的：只有当存在多个实现（如真实实现 + 测试替身）时，接缝才真正成立 为可测试性设计： - 接受依赖：通过参数或构造函数显式传入依赖，而非内部硬编码 - 返回结果：避免副作用，优先通过返回值传递结果 - 小表面积：接口尽量小，只暴露必要功能，减少测试负担 加深一簇浅模块的策略： 按依赖类别划分，决定测试策略与端口适配器： - 进程内依赖（如其他内部模块）：通过接口抽象，使用依赖注入 - 本地可替代依赖（如配置文件、本地服务）：提供默认实现 + 可替换适配器 - 远程自有依赖（如内部微服务）：封装为明确接口，使用客户端适配器 - 真外部依赖（如第三方 API）：通过适配器隔离，便于 mock 和替换 “设计两次”方法： 并行产出 3 个以上截然不同的接口方案，再按以下维度比较： - 深度：接口是否简洁、功能是否集中 - 局部性：相关逻辑是否集中，调用方是否需跳转多处 - 接缝位置：依赖是否可替换，测试是否容易 最终给出有主见的推荐，而非罗列选项 覆盖场景： - “合成一个深模块”：将多个浅模块按功能聚合，设计统一高层接口，隐藏内部碎片 - “截然不同的接口”：避免微调式变体，追求本质不同的抽象方式（如命令式 vs 声明式、同步 vs 异步） - “一堆内部函数”：识别是否可聚类为有明确职责的模块，通过接口封装，提升局部性与可测试性 改编自 Matt Pocock 的 codebase-design（MIT）。

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本