软件工程 / 架构设计方法论知识图谱 / 分组目录 / 本质层 / 深模块与浅模块
essence · H · P1 · active

深模块与浅模块

Deep vs Shallow Modules
P1进阶verified本质 essence方法原则H · 实现与构造GL-ESSENCE · 本质层

§1摘要与结论

TL;DR · 一句话结论

以“接口复杂度与所提供功能之比”评价模块的两种形态：深模块提供强大功能却只有简单接口，浅模块接口相对复杂却功能不足，未能隐藏显著复杂度。

别名：deep module、shallow module、classitis、深模块、浅模块　|　英文：Deep vs Shallow Modules　|　类型：方法原则 / concept

§2局部关系图

深模块与浅模块 的 1-2 跳邻域关系图前置依赖（prerequisite）：关注点分离是信息隐藏的前提前置依赖（prerequisite）：理解信息隐藏是评估内聚耦合的前提对照（contrasts）：抽象泄漏揭示信息隐藏的固有边界组合（combination）：信息隐藏与关注点分离常组合使用组合（combination）：SOLID 管职责与替换性，组合优先管复用机制细化（refines）：SOLID 以职责划分细化高内聚低耦合判据前置依赖（prerequisite）：职责划分与替换性判据是理解模式适用性的前提细化（refines）：模式是被命名的内聚与解耦结构解法组合（combination）：模式以稳定接口封装变化，呼应深模块对照（contrasts）：模式封装复杂度，抽象泄漏标明其边界依据推导（derives_from）：持续设计投入以降低长期认知负荷为目标依据推导（derives_from）：战略式设计以职责划分与替换性为判据依据推导（derives_from）：可读性治理以可读性为工程属性为前提依据推导（derives_from）：评审以高内聚低耦合作为结构判据组合（combination）：持续设计投入与代码评审共同对抗结构腐化案例印证（case_instance）：印证：七层职责分解与分层坐标案例印证（case_instance）：印证：分层架构风格的工业级实例案例印证（case_instance）：违背：巨型单文件偏离深模块与信息隐藏理想前置依赖（prerequisite）：模块化目标是信息隐藏判据的前提前置依赖（prerequisite）：模块划分质量以内聚耦合衡量前置依赖（prerequisite）：关注点分离是理解与选择架构风格的认知基础前置依赖（prerequisite）：信息隐藏是理解深/浅模块的前提前置依赖（prerequisite）：信息隐藏是判断继承/组合取舍的前提依赖关联（dependency）：继承在父子类之间引入实现层耦合前置依赖（prerequisite）：深模块降低认知负荷，支撑可读性组合（combination）：模块化是关注点分离在结构上的体现依据推导（derives_from）：信息隐藏模块分解是信息隐藏原理的方法化深模块与浅模块深模块与浅模块（ESS-H-05）Hermes 七层架构总…Hermes 七层架构总览（CAS-X-11）信息隐藏信息隐藏（ESS-H-01）可读性与认知负荷可读性与认知负荷（ESS-H-07）设计模式与反模式设计模式与反模式（ESS-H-09）内聚与耦合内聚与耦合（ESS-H-02）关注点分离关注点分离（ESS-G-01）代码复审与可读性治理代码复审与可读性治理（MTH-H-04）模块化与分解模块化与分解（ESS-G-04）架构风格架构风格（ESS-G-05）SOLID 职责划分与替…SOLID 职责划分与替换性（ESS-H-08）战略式编程与持续设计投入战略式编程与持续设计投入（MTH-H-03）抽象泄漏抽象泄漏（ESS-H-04）组合优于继承与脆弱基类组合优于继承与脆弱基类（ESS-H-06）信息隐藏模块化分解信息隐藏模块化分解（MTH-H-02）
前置依赖实现依据推导案例印证对比冲突
以本节点为中心，静态内联 1–2 跳邻域：内环 4 个直接邻接、外环 10 个二跳节点，共 15 个节点；连线按边类型着色（六类配色见下）。构建期计算，无运行期脚本。

§3原理 · 为什么

设计目标始终是降低理解与修改系统所需的认知负担，而复杂度主要来自依赖与不透明：开发者需要在脑中同时持有的信息越多、越不显见，系统就越难改。模块是把复杂度封装在接口之后的单位，因此它的价值取决于接口替使用者省去了多少内部信息。若接口本身复杂，或者大量方法只是把调用透传到别处，隐藏就形同虚设。深模块以简单稳定的接口承载丰富功能，把选择与内部结构留在内部，是信息隐藏在接口粒度上的自然延伸；判断一个设计好坏的最终标准，是它是否减少了使用者必须掌握的信息。 “深”强调的是一种信息比例：使用者只需掌握少量概念即可正确调用，其余复杂度被封装在内部，从而把理解成本从众多调用方转移到一个模块内部并由其集中承担，避免每个使用者各自重复理解同一套细节。 换句话说，模块的价值不在其内部实现有多么精巧，而在于它能否让调用方以很少的知识获得很多能力。

§4机制 · 如何运作

评价一个模块是否“深”，看它对外暴露的概念数量与该模块实际完成的工作量之比：接口越小而功能越完整，就越深；反之接口相对于功能越大，就越浅。追求深模块意味着在保持接口简单的前提下把功能与设计决策收进内部，拒绝仅为拆分而拆分的细碎接口。若沿这条路径反向发展，就会出现大量只提供极少功能、接口却相对复杂的浅模块，系统由“类型与接口数量增长”而非功能增长驱动复杂度上升，形成所谓的类爆炸。这种增长不是功能需要，而是接口粒度选择不当的产物。 深模块通常伴随对实现细节的主动隐藏与对常见用法的默认化——把最常用的路径做成简单入口，把罕见选项作为可选参数，使简单用例保持简单，同时不牺牲能力较强场景所需的表达力。 因此“深”是相对于使用者而言的：同一个模块对熟悉内部的人可能并不深，但对必须依赖其接口的调用方，接口的简洁程度决定了它是否值得被复用与依赖。 接口的简洁本身并不足够，还必须同时保持稳定。

§5工程 · 怎么落地

设计时优先追问“这个接口让调用方必须知道多少”，而不是“函数是否足够短”。允许模块在一定程度上通用：功能可以聚焦当前需求，但接口应足够通用以支持多种用法，避免把接口绑死在单一场景；同时警惕过度专门化，它往往是复杂度的重要来源。合并透传方法与没有实质封装价值的浅模块，把强功能收敛到简单接口之后；对必须暴露的接口保持稳定，让内部实现能够自由调整。设计评审时可以对比接口的使用示例与实现体量，体量大而接口小的方向通常更健康。 重构时优先消除透传方法与只会转发调用的中间层；当发现大量小类型仅承担转发职责时，考虑合并或上移其逻辑，减少读者为了理解一条调用链而必须跨过的边界数量。 另一个可操作的检验是“能否只看接口文档就正确使用”：若不能，接口很可能泄漏了过多实现约束，或缺少必要的默认与约定，应优先改进接口而不是补充说明。

§6权衡卡

反例 · 误区

反例是浅模块与类爆炸——大量只有极少逻辑的单元相互调用，读代码需要在数十个接口之间跳转，认知负荷不降反升。

原文要点
  • 深模块并非越大越好，也有失效模式。
  • 把过多无关功能塞进一个接口，会使模块承担多个变更原因、内聚下降，最终成为难以替换的庞然大物；反之，过早追求通用接口可能引入当前根本用不到的能力，属于投机式通用化，反而增加需要理解的表面。
  • 两个方向的张力说明接口设计需要判断力：既要让接口简单到无需了解内部，又不能简单到把本应区分的关注点混在一起。
  • 因此应把“深”作为方向而非阈值，结合变更频率判断粒度。
  • 判断“深”也要防止另一种偏差：把复杂度藏得过深会使故障定位与调试变难，因为内部状态不再可见；因此隐藏应针对实现细节，而不是针对诊断所需的关键行为，必要时以可观测的反馈弥补。

权衡原文仅按显式标记词归栏引用（收益 / 代价 / 反例），其余句子按原序列为「原文要点」；内容逐字引用未改写。

§7学习路径条

ESS-H-01信息隐藏→ESS-H-05深模块与浅模块→ESS-H-07可读性与认知负荷

§8案例带

CAS-X-11 · 经 direct

Hermes 七层架构总览

对八千余文件的工业级 AI Agent 项目做七层架构总览逆向，揭示其「越用越聪明」的自进化闭环如何在层间传导的控制型架构案例。

CAS-X-01 · 2 跳派生：当前节点 → ESS-H-01 → ESS-G-01

去中心化聊天架构逆向

对一个仅有 58 份设计文档、尚未实现的开源去中心化聊天项目做架构逆向：从设计文本提炼 18 个模块及其依赖关系，重建模块依赖 DAG 与三条核心数据流 DAG，并输出全景理解与深度需求分析。

CAS-X-02 · 2 跳派生：当前节点 → CAS-X-11 → ESS-G-05

网申填写扩展逆向架构

对 Chrome MV3 网申自动填写扩展的逆向架构分析：梳理 popup、content、background、options 四模块职责，解剖 12 个站点适配器、双通道消息协议与隐私脱敏机制，并评估其零依赖零构建选型。

CAS-X-03 · 2 跳派生：当前节点 → CAS-X-11 → ESS-G-04

网申 v3 多模块解耦

一套面向高可扩展性的网申信息速查扩展架构：以 schema.js 为唯一数据驱动源，把数据模型、存储、纯函数与渲染组织为严格单向依赖的共享层，供 popup 与页面浮层双容器复用，并先立跨模块接口契约。

CAS-X-05 · 2 跳派生：当前节点 → ESS-H-01 → ESS-H-02

preset 通道耦合分析

对 harness「委派工具层→续用管理器→preset 服务→MCP 服务器」这条通道做耦合分析：识别契约、服务定位、数据契约、组合语义、路径与装配一致性六类耦合点，定位「静默丢弃特化」与「装配漂移」两处实质缝隙。

CAS-X-07 · 2 跳派生：当前节点 → ESS-H-01 → ESS-H-04

插件 DAG 两次级联升级

在同一知识库上继续两轮上游级联升级：处理数百次提交与包的增删，暴露「依赖声明不等于运行时引用」、分层须按最长路径深度、纯外部依赖边不得入主图等差分陷阱，并以全量门控校验收口。

CAS-X-13 · 2 跳派生：当前节点 → ESS-H-01 → ESS-G-01

Claude Code 架构逆向

以社区逆向源码、系统提示词与官方文档三源交叉验证，还原一个商业 Agent 的查询引擎、子Agent、工具与权限体系的逆向分析案例。

CAS-X-15 · 2 跳派生：当前节点 → ESS-H-07 → MTH-H-04

Open Code Review 图谱

对阿里开源 AI 代码审查 CLI 做源码级解析并构建「知识 + 实践资产 + AI 索引」三合一知识图谱的工程案例。

§9信源与核验

核验状态True（verified）
置信度high
复核日期2026-09-10
生命周期active
规范信源BK-008、PAP-002、STD-005
入口链接https://web.stanford.edu/~ouster/cgi-bin/book.php　https://www.win.tue.nl/~wstomv/edu/2ip30/references/criteria_for_modularization.pdf
勘误
常见误解：深模块指代码行数很多的模块
核验结论：深/浅由接口复杂度与所提供功能之比决定，与代码行数无必然关系；接口简单而功能强的模块为深，接口相对功能复杂的为浅　[BK-008]

§10原始关系清单

展开：本节点的全部原始关系边（4 条，含边 ID 与方向）
关系方向对端节点说明
案例印证← CAS-X-11Hermes 七层架构总览
E-974		违背：巨型单文件偏离深模块与信息隐藏理想
组合← ESS-H-09设计模式与反模式
E-745		模式以稳定接口封装变化，呼应深模块
前置依赖← ESS-H-01信息隐藏
E-107		信息隐藏是理解深/浅模块的前提
前置依赖→ ESS-H-07可读性与认知负荷
E-110		深模块降低认知负荷，支撑可读性