深模块设计

架构退化的常见痛点

在日常开发中，我们常会遇到这样的困境：代码表面看似规整，内部却千疮百孔。很多模块只是对底层逻辑的简单透传，接口庞杂且实现薄弱。这种“浅模块”迫使调用方了解大量不必要的细节，导致修改一处逻辑就需要在 N 个调用点重复修复。更糟糕的是，深层业务逻辑被硬编码在实现中，无法在接缝处被 Mock 或替换，最终让测试变得极其脆弱。

深模块的核心工作流

这套技能的核心在于引入一套精确的设计词汇，帮助开发者通过“小接口 + 大量实现”来重组代码结构。它的工作流包含以下关键步骤：

• 词汇统一：严格定义 Module、Interface、Depth、Seam 等概念，避免将其混淆为 component 或 service。
• 深化诊断：运用“删除测试”启发式——想象删掉该模块，如果复杂度消失则是透传；若复杂度重现到调用方，说明它在创造价值。
• 接缝定位：遵循“一个适配器是假设，两个适配器是真实”的原则，寻找可以通过依赖注入改变行为的 Seam。
• 可测性改造：强制遵循“接受依赖而非创建依赖”、“返回结果而非副作用”的原则，确保调用方与测试走同一接口。

适用边界与注意点

这套技能适用于重构接口、寻找深化机会以及提升 AI 导航性的场景。但必须注意，它要求极高的术语一致性：不能把“模块”随意称为 API 或 boundary。深度是接口的属性，深模块内部依然可以包含小的、可替换的部件，但它们不应暴露在接口签名中。如果你只是需要一个简单的数据结构封装，请寻找其他轻量级方案。