模块化与分解
§1摘要与结论
模块化与分解指的是把整体切成若干能够各自独立运转的较小单元，使每个单元的扩容、部署与故障处置不再被其余部分牵连。它被视为可伸缩性最通用的一条做法，因为服务化、数据分片、流式处理以及节点各自持有本地资源的形态，底层走的都是同一条思路。定义的重心并不落在切这个动作上：真正的判定标准是切完之后各单元能否在负载增长时被单独放大。哪些职责应当留在一起、哪些应当分开，并没有通用答案，因此分解的边界是相对的，取决于当前负载形态与团队条件，而不是可以照抄的结构模板。切得过细同样会反噬。 判断边界是否合理，有一个可操作的观察点：某单元能否在不牵动邻单元的前提下完成一次容量调整或一次故障切换。
别名：modularity、decomposition、module、模块化、系统分解 | 英文：Modularity and Decomposition | 类型：方法原则 / concept
§2局部关系图
§3原理 · 为什么
拆分之所以被当作通用伸缩原则，是因为它让各部分能各自扩容、各自部署，服务化、分片、流处理与无共享架构都以它为前提。但原则本身不是难点，难点是划边界：哪些东西应当合在一起、哪些应当拆开，并没有通用答案。反面情形同样清楚，拆得过细会引入跨节点的协调、一致性、可观测性与部署成本，反而拖慢整体。因此适用边界是：只有当独立运行带来的扩容与解耦收益，超过协调与运维的额外代价时才成立；负载特征尚未摸清、单机尚能应付时，过早拆分往往得不偿失。优秀架构常是多种形态的务实混合。 这条原则在操作上还要求把收益与代价写成可核对的条目，而不是停留在直觉层面。收益一侧应说清哪条瓶颈被解除、峰值容量因此提高多少、某类变更的发布是否可以不再牵连其他部分；代价一侧应说清新增了哪些跨单元调用、这些调用失败时的行为、排障时需要同时查看几处、以及团队是否具备相应的运维能力。两边对照之后若仍分不出高下，说明拆分的前提尚未成立，此时更稳妥的做法是先保留单体形态，用纵向扩充与就地优化顶过当前阶段，同时把观察指标补齐，等真实的增长曲线出现再决定切法。原则的适用还有时间维度：负载形态与团队规模都会变，去年合适的边界今年可能过窄或过宽，因此边界需要被周期性复核，而不是一次划定就永久沿用。若答案是否定的，说明这条边界只是名义上的划分，实际运行仍被绑在一起。另一个观察点是故障与负载的分布规律，应当把总是一起失效、总是一起变忙的部分留在同一单元，把资源需求形状差异很大、变更频率差异很大、责任归属不同的部分分开。分解还要与数据归属一起考虑，计算被切开而数据仍集中一处时，伸缩收益往往兑现不了。单元之间只应通过显式契约交互，接口越窄、越稳定，独立演进的空间就越大，也越容易在需要时把某一块单独放大或替换。反过来，若两块之间需要频繁的双向往返与共享事务，把它们强行拆开只会制造持续的协调负担，此时合并反而是更清醒的选择。
§4机制 · 如何运作
分解之所以换来伸缩能力，机制在于资源归属与协调路径的改变。共享内存方案把并行度押在同一台机器的多核与大内存上，代价是价格随规格超线性上涨，而且单机规格放大一倍通常带不动两倍负载。共享磁盘方案让多台机器共用一组盘阵，却要承受资源争抢与加锁开销，伸缩性因此受限。节点各自持有本地计算与存储、彼此只通过网络在软件层协商的形态则不同：负载上升时补节点即可分摊，硬件可按性价比挑选，还能把副本摊到不同机房以增强容错。它的代价同样由机制决定，数据必须先显式划分，协调、一致性与部分失败等分布式难题也随之全部进来。 把这三种形态并排看，差别可以归结为并行度由谁提供。前者由单机的处理器与内存提供，因此上限被单机规格锁死；居中者由共享介质提供，但介质本身成为争抢焦点，加锁与排队会把新增的机器吞掉；后者由节点数量提供，理论上可以持续追加。这也解释了为什么无共享形态常被当作可伸缩性的参照：它把增长问题转换成采购与调度问题，代价是每一次跨节点交互都要面对延迟不确定、顺序不确定、对方可能已经不存在这三件事。因此分解在机制上并没有消除复杂度，它只是把复杂度从硬件规格的天花板搬到了软件协调的地板上，前者可以用钱缓解，后者只能靠设计与纪律缓解，而后者恰恰更难。
§5工程 · 怎么落地
落到工程实现，一个现代变体是把存储与事务执行拆成两类服务：计算侧可以开很多个，共同读写同一份存储服务，而该服务暴露的不是文件系统或块设备这类通用接口，而是针对数据库访问特征定制的专用接口。这样既保留了多计算节点共享一份数据的便利，又绕开了早期共享磁盘架构的争抢与锁开销。工程上还须补齐分解带来的配套动作：把数据分布规则显式写出来，为节点增减设计再平衡流程，并为跨节点调用准备超时、重试与幂等语义。缺少这些配套，分解只增加了拓扑复杂度，并不能真正换来可伸缩性。 配套动作还可以列得更细。数据分布规则要写成可执行的判据，让写入路径能自行算出目标单元，而不是依赖人工约定；节点增减要有预热与回填流程，避免新单元一上线就被整段流量压垮；跨单元调用要区分可重试与不可重试的错误类型，并给写操作带上幂等标识，否则超时后的自动重试会制造重复记录。容量评估要按单节点能力做线性外推并留出余量，因为节点越多，同时出问题的概率越高。关键决策应留下简短记录，写清当时的分片依据与预期负载，日后边界需要调整时才有据可依。最后，分解之前值得先尝试更轻的手段，例如读写分离、冷热数据分层、把无状态部分与有状态部分分开，这些做法往往能在不引入完整分布式复杂度的前提下解除大部分瓶颈，只有当它们都不够用时，才值得动真正的切分。
§6权衡卡
分解并非没有代价，取舍的核心是收益与协调成本谁更大。
更值得注意的是反向风险：在用户与需求都还不清楚的新产品上，为假想的未来规模提前拆分，轻则白费力气，重则把设计锁死在难以调整的形状里，反而拖累演化。
这些代价都随规模增长而非线性累积，因此分解的收益曲线通常前段陡、后段平，越过某一点后继续拆分反而整体变差。
其二是跨单元事务的代价，一旦原本一次本地提交变成多段提交，失败路径会成倍增加，回滚与补偿逻辑本身成为新的缺陷来源。
- 一个对照能说明尺度差异：每秒十万个小请求的系统，与每分钟三个大请求的系统，即便聚合吞吐相同，形态也会完全不同，所以适配某一档负载的切法多半撑不住十倍之后的负载，负载每上一个数量级，架构就得重新审视一次。
- 结论是分解的时机与粒度应当由已观测到的瓶颈驱动，而不是由对未来规模的想象驱动。
- 还有几处具体取舍值得单独点出。
- 其一是读写放大与协调开销的对立：单元划得越细，单次请求需要串联的环节越多，尾延迟越难控制；划得越粗，单点容量上限越早到来。
- 其三是热点问题不会因为拆得更多而消失，某个键或某个租户的流量若天然集中，增加单元数量对它毫无帮助，只能从分区规则或访问方式上另想办法。
- 其四是可观测性的边界效应，调用链跨越的单元越多，一次排障需要拼接的信息越多，平均修复时间随之上升。
- 实务上的判断依据应当是实测的瓶颈位置与增长速率，而不是同行采用了什么形态。
权衡原文仅按显式标记词归栏引用（收益 / 代价 / 反例），其余句子按原序列为「原文要点」；内容逐字引用未改写。
§7学习路径条
§8案例带
网申 v3 多模块解耦
一套面向高可扩展性的网申信息速查扩展架构：以 schema.js 为唯一数据驱动源，把数据模型、存储、纯函数与渲染组织为严格单向依赖的共享层，供 popup 与页面浮层双容器复用，并先立跨模块接口契约。
Hermes 七层架构总览
对八千余文件的工业级 AI Agent 项目做七层架构总览逆向，揭示其「越用越聪明」的自进化闭环如何在层间传导的控制型架构案例。
去中心化聊天架构逆向
对一个仅有 58 份设计文档、尚未实现的开源去中心化聊天项目做架构逆向：从设计文本提炼 18 个模块及其依赖关系，重建模块依赖 DAG 与三条核心数据流 DAG，并输出全景理解与深度需求分析。
网申填写扩展逆向架构
对 Chrome MV3 网申自动填写扩展的逆向架构分析：梳理 popup、content、background、options 四模块职责，解剖 12 个站点适配器、双通道消息协议与隐私脱敏机制，并评估其零依赖零构建选型。
网申 v2 深度重构
一次由「改一处漏多处」症状触发的深度重构：定位到接口定义散落 12 个文件、存在 7 种接口形态的根因后，以单一契约源、dispatch 消息表与能力注册中心重建三层契约系统，恢复可审计与可校验性。
preset 通道耦合分析
对 harness「委派工具层→续用管理器→preset 服务→MCP 服务器」这条通道做耦合分析：识别契约、服务定位、数据契约、组合语义、路径与装配一致性六类耦合点，定位「静默丢弃特化」与「装配漂移」两处实质缝隙。
插件 DAG 两次级联升级
在同一知识库上继续两轮上游级联升级：处理数百次提交与包的增删，暴露「依赖声明不等于运行时引用」、分层须按最长路径深度、纯外部依赖边不得入主图等差分陷阱，并以全量门控校验收口。
dsh-manager 插件深度分析
以「编译依赖、运行时注入、组合装配」三硬依据加源码行号，对第三方插件做依赖、功能、需求溯源与设计问题裁决，并复用上游 DAG 知识库节点标识，使分析结果可与主图互查。
harness 源码架构解析
对 deepseek-harness 官方源码做分层解析：镜像官方架构文档，按九个层与九十余模块建立文档集群，产出跨层联动矩阵与七条关键路径，并钉住「模型可见即已记录」、能力缝三角等设计不变量。
dsh 插件依赖增量定位
以官方插件 DAG 为蓝本，对一个官方清单之外的全新社区插件做功能定位与依赖位置增量分析，产出可下钻交互依赖图与多形态文档的源码级架构逆向案例。
Claude Code 架构逆向
以社区逆向源码、系统提示词与官方文档三源交叉验证，还原一个商业 Agent 的查询引擎、子Agent、工具与权限体系的逆向分析案例。
Open Code Review 图谱
对阿里开源 AI 代码审查 CLI 做源码级解析并构建「知识 + 实践资产 + AI 索引」三合一知识图谱的工程案例。
§9信源与核验
核验结论：Parnas 把 module 定义为 responsibility assignment（责任分配），主张为高效实现而放弃“模块=子程序”假设 [PAP-002]
核验结论：模块化效果取决于划分模块所依据的判据（criteria），按信息隐藏切分与按处理步骤切分可修改性差异显著 [PAP-002]
§10原始关系清单
展开：本节点的全部原始关系边（5 条，含边 ID 与方向）
| 关系 | 方向 | 对端节点 | 说明 |
|---|---|---|---|
| 案例印证 | ← CAS-X-03 | 网申 v3 多模块解耦 E-945 | 印证：共享层严格单向依赖实现模块化与可独立变更 |
| 案例印证 | ← CAS-X-11 | Hermes 七层架构总览 E-972 | 印证：七层职责分解与分层坐标 |
| 组合 | → ESS-G-01 | 关注点分离 E-111 | 模块化是关注点分离在结构上的体现 |
| 前置依赖 | → ESS-H-01 | 信息隐藏 E-101 | 模块化目标是信息隐藏判据的前提 |
| 前置依赖 | → ESS-H-02 | 内聚与耦合 E-102 | 模块划分质量以内聚耦合衡量 |
附对照资源 · 12factor 子库
| 12factor 节点 | 关系 | 对照说明 |
|---|---|---|
| 工具即结构化输出 ag-tools | 跨体系对照 | 工具即可组合单元，对应模块化分解与粒度/边界设定 |
| 小而专注的 Agent ag-small | 跨体系对照 | 小而专注的 Agent 对应模块化分解与细粒度单元边界 |