刚开始做系统架构的时候，我把“模块划分”理解成“多建几个文件夹”，把“依赖关系”理解成“谁能调用谁”。几年下来，在几个大型后端项目里反复重构之后，我才意识到这两件事远不是目录和权限那么简单——模块划分的核心是边界封装，依赖关系的核心是方向治理。这两个问题处理不好，代码库会随着业务膨胀逐渐失控，最终变成那个经典画面：改一个接口，连带崩掉五个模块，谁都不敢动。
这篇文章不打算讲理论概念，我把之前重构一个交易类项目时踩过的坑、总结出的判断标准、用过的工具和实测有效的执行方案完整梳理一遍。如果你正在做系统架构设计、准备拆服务，或者被自己代码库里错综复杂的调用关系折磨，这篇内容应该能提供一套可直接上手的思路。
1. 先认清一个事实：模块不等于一个目录
很多团队声称自己做了模块化，打开代码仓库一看，确实有user、order、payment、coupon这样的顶层 package，但点进去就会发现：A 模块的 Service 直接 new 了 B 模块的 Mapper，B 模块的工具类又反向调用了 A 模块的配置类。这种情况下，所谓的“模块”顶多算代码分组，不是真正的模块化。
把模块分组和真正的模块化区分开，是走上正轨的第一步。分组只是把文件按名字归拢，模块则要回答三个问题：
- 这个模块对外暴露什么？（不暴露的实现细节内部消化）
- 这个模块依赖谁？（只通过明确接口依赖，不跨模块直接new）
- 这个模块能否独立测试和替换？（如果替换一个模块会炸掉整个系统，说明边界是假的）
我自己判断模块划分好坏的简单标准就是：能不能做到“内部怎么改，对外接口不变，其他模块无感”。很多项目做不到这一条，其实是因为当初划分模块时只考虑了“把谁和谁放一起”，没考虑“谁能够知道谁的存在”。
1.1 模块间的依赖不应该靠自觉约束
如果你问不少团队“你们的模块间调用有没有规则”，他们能答上来“只有上层才能依赖下层”或者“domain 层不能依赖 infrastructure 层”之类的话。但你再问“这个规则怎么保证”，多半得到的答案是：“Code Review 的时候看看啊”“违反了再改呗”。
人肉约束的问题在于，随着项目周期拉长、人员流动、需求压力变大，依赖关系一定会向混乱方向漂移。这就像一条没有护栏的山路，平时没人往悬崖下开，但凡是雨天、夜里、疲劳驾驶，事故率就上来了。真正可靠的依赖治理，必须把规则固化到工具层面：有自动检查、有CI拦截、有直观的依赖可视化。具体工具方案我放在后面专门讲，这里先强调一个观念：依赖关系是系统架构的“路网”，不是某几个工程师的“口头承诺”。
1.2 高内聚、低耦合在模块层面的真实含义
“高内聚、低耦合”这六个字被说滥了，但真正落地时很多人理解偏了。我之前帮朋友团队看一个电商项目，他们把优惠券模块拆成了coupon_new、coupon_hot、coupon_expired这种按状态拆的方式，结果每个子模块都要做“过期处理”“防刷校验”“计入报表”三件套，大量逻辑重复。这就是典型的按“数据状态”分，而不是按“业务能力”分。
正确的内聚标准应该按照变化原因来划分：一段逻辑会因为同一个业务需求调整而一起变化，那它们就该进同一个模块；如果两段逻辑各自会因为完全不同的原因变化，哪怕它们看起来关系很近，也应该拆开。优惠券的例子后来重构成了coupon_define（券定义）、coupon_issue（券发放）、coupon_verify（券核销）、coupon_reconcile（券对账）四个模块，每个模块变化原因单一，互相不需要知道对方内部怎么做，边界自然就清晰了。
这个“按变化原因划分”的思路，业界有个灰常重要的名词叫共同封闭原则（Common Closure Principle），它在模块设计里的地位不亚于SOLID在类设计里的地位。理解了这一点，很多模块划分争议都能迎刃而解。
2. 模块划分的实操标准：四个维度、两个顺序
光有原则不够，落盘的时候总得有个可执行的检查表。我在反复试错中沉淀了一套自己的模块划分流程，每次设计模块或者评审别人的模块设计时都会过一遍，准确率很高。
2.1 四个划分维度的取舍
第一个维度是业务能力。订单模块管下单、支付模块管收钱、库存模块管扣减，这是最符合业务直觉的。这种划分好在语义清晰，产品经理、测试、新入职的工程师都能快速理解。
第二个维度是技术通用能力。比如消息发送、文件存储、鉴权、日志上报，这些跟业务无关的能力单独抽成基础模块。问题在于，有些团队会过度使用这个维度，把技术分层当成模块划分，结果搞出controller模块、service模块、mapper模块，这种纯水平切割没有任何业务边界，一遇到跨模块的业务流就会产生绕过边界的调用。
第三个维度是变化频率。稳定不变的底层能力（日志框架、配置读取）放在底层，业务变化快的模块放在上层。这个维度适合用来“定层级”，不适合单独用来“定模块”。
第四个维度是团队所有权。如果模块边界跟团队边界一致，每个模块有且只有一个团队负责，那沟通成本会低很多。这个维度在大公司非常关键，但如果你是一个小团队或者个人项目，没必要优先考虑。
2.2 我推荐的划分顺序
我的实际操作顺序是：先业务能力，再变化频率，再技术通用能力，最后看团队边界。
举个例子，假设我们要设计一个内容社区系统。按业务能力可以初拆出：用户、内容、评论、关注、消息、审核。然后看变化频率：审核规则这半年基本不动，但反垃圾策略一周变三次，所以“审核”模块内部要拆成“审核引擎”（稳定）和“策略中心”（易变），策略中心对外提供接口，审核引擎消费策略中心的配置。再看技术通用能力：图片处理、短链生成、文本过滤这些能力，如果同时被内容和评论两个模块用到，就抽成基础能力模块，但所有基础能力模块必须明确“只被上层业务模块依赖，自己不能反向依赖业务模块”。最后才根据团队规模做合并或拆分。
这套顺序的好处是，每一步的划分理由都能被追溯，评审时不会出现“我就是觉得该这么拆”这种主观争论。
2.3 模块大小的判断：大模块要看内部凝聚力
总有人问“一个模块到底应该多大”。我的回答很直接：模块大小没有统一代码行数标准，但有一个非常实用的判断方法——看内部凝聚力是否足够。把某个模块的代码全部打开，如果里面超过三成内容跟这个模块对外承诺的职责没有直接关系，那说明这个模块塞了太多不该有的东西。
我自己会用一个简单办法做“瘦身检测”：找模块里最核心、最稳定的那个领域对象（比如订单、商品、用户），看除了这个对象自己之外，模块里声明的其他类是不是都围绕它为业务目标服务。如果模块里出现了大量“数据转换工具类”“通用枚举类”“不知道给谁用的配置类”，那几乎可以断定模块边界出问题了。
3. 依赖关系的核心规则：方向、层级和倒置
模块划分定了边界，依赖关系就是边界的“桥梁”和“路网”。路修得合理，各处互联互通又不互相干扰；路修得乱，堵车、绕路甚至断头路都是家常便饭。我在依赖关系治理上总结出三条核心规则，全部踩过坑，全部付出过代价，才真正领悟。
3.1 依赖方向必须单向收敛
最危险的情况是循环依赖。A 依赖 B，B 又依赖 A，这种情况初期两个模块都能编译能跑，但随着版本演进，A 和 B 会越来越像“连体婴”，每次上线只能一起发布，每个 bug 都可能跨越两个模块，测试复杂度翻倍。
我记得有一次，支付模块要改一个退款状态字段的类型，本来只是一个小改动，结果发现订单模块里有一个服务在消费支付模块的字段，支付模块又反向调了订单模块的一个查询接口。这个“双向依赖环”导致最后不得不同时改三个发布包，还要协调五个工程师一起联调，一个半小时的活干了一整天。
打破循环依赖的常规手段是依赖倒置：在 A 和 B 各自身边定义一个抽象接口（或者放进一个第三方模块），让 A 和 B 都依赖那个抽象，而不是互相依赖具体的实现类。这样物理上切断循环，逻辑上两端仍能协作。很多工程师怕“多写接口”，但跟循环依赖后续付出的维护成本比，多写那几行接口的代价几乎可以忽略。
3.2 依赖必须分级，而“层”与“模块”要共存
纯技术分层（表现层、业务层、数据层）在单体早期很清晰，但业务一复杂就会出问题。比如“订单下单”这个流程：它既属于业务层，又要调用数据层，还会触发风控、优惠、消息通知。如果严格按技术三层走，所有模块的业务逻辑都要挤在同一层，那个层会变成一个无法拆分的巨无霸。
所以我的做法是**“业务模块优先 + 技术层辅助”的混合模式**：业务模块之间严格独立，每个业务模块内部再按“接口层—应用层—领域层—基础设施层”做技术分层；跨模块只能走接口，不能跨模块读写对方的数据库表。这么设计后，依赖关系就变成“模块间看业务，模块内看技术”，既有业务边界，又有分层约束。
统一的标准是：上层业务模块可以依赖下层基础模块，基础模块绝对不能反向依赖上层业务模块；同一层模块之间尽量少依赖，如果有依赖必须走接口，且依赖方向要单向。
3.3 稳定方向原则：让易变的依赖“向下流动”
有些团队模块边界画得很漂亮，但依赖方向画反了：核心业务模块被一堆边缘功能模块依赖，或者高层策略代码直接依赖了底层细节实现。比如内容社区里，帖子详情页需要调用风控模块判断是否展示，结果风控模块被设计成依赖帖子实体类——一旦帖子实体类改了，风控反而要跟着变。
正确的方向是：稳定、不常变化的东西应该被依赖；易变、经常调整的东西不应该被底层依赖。所以风控模块应该依赖一个抽象的“内容对象”接口，而帖子模块提供这个接口的实现。依赖关系的箭头要从变化多的模块指向变化少的模块。这个原则我习惯称之为“让依赖指向稳定”，它是避免模块腐化的长期护身符。
4. 依赖关系的可视化与自动化拦截
前面讲的大部分是“应该怎么做”，但理想和现实之间隔着一条鸿沟：实际的代码库随需求日积月累，没人能保证所有人永远按照当初的架构约定执行。我见过太多架构文档写得天衣无缝，三个月后代码和文档已经完全对不上。靠文档约束不靠谱，必须依赖工具做持续检查。
4.1 依赖图工具：先看见，再治理
要治理依赖关系，第一步是先把它看清楚。我用的工具组合比较杂，不同语言的生态各有妙招：
| 语言/生态 | 推荐工具 | 主要用途 |
|---|---|---|
| Java | ArchUnit / JDepend | 编写依赖规则用例，CI自动验证 |
| TypeScript/JavaScript | dependency-cruiser | 依赖图可视化、依赖规则检查、循环依赖检测 |
| Go | go list + godepgraph | 包依赖关系梳理和可视化 |
| Python | pydeps / import-linter | 模块依赖检测和架构规则约束 |
| C# | NetArchTest | 类似ArchUnit的架构测试 |
以 Java 项目为例，我用 ArchUnit 写过一组架构测试用例，效果拔群：
@AnalyzeClasses(packages = "com.example") public class ArchitectureTests { @Test void services_should_only_depend_on_their_own_interfaces() { JavaClasses classes = new ClassFileImporter().importPackages("com.example"); ArchRule rule = noClasses() .that().resideInAPackage("..service.impl..") .should().dependOnClassesThat() .resideInAnyPackage("..service.impl..", "..domain..") .ignoreDependencyOnClassesThat() .resideInAPackage("..common.."); rule.check(classes); } @Test void no_cycles_between_packages() { JavaClasses classes = new ClassFileImporter().importPackages("com.example"); ArchRule rule = slices() .matching("com.example.(*)..") .should().beFreeOfCycles(); rule.check(classes); } }这两段测试一旦放进 CI，任何人在合并代码前跑一遍单测就能暴露依赖违规。实际上我把它当架构守卫用，效果极好：团队里流传着“架构不是你说了算，测试说了算”的调侃。
前端的思路也类似。用 dependency-cruiser 可以生成整个项目的依赖关系图，然后通过配置文件声明规则，比如：
{ "forbidden": [ { "from": { "path": "^src/pages" }, "to": { "path": "^src/utils" } } ] }规则的含义是：页面层代码不允许直接依赖 utils 工具层。打破这个规则的代码会自动被 CI 拦截。前端很多人习惯“随意 import”，有了这类工具之后，模块边界才真正有了约束力。
4.2 依赖矩阵：人工审计的杀手锏
自动化工具看的是“当前代码快照”，但架构演进还需要“整体视角判断”。我的做法是每个季度手工做一次依赖矩阵审计：把所有模块罗列为行列，交叉点标注“列模块是否依赖行模块”。
举个例子，某个系统的模块依赖矩阵（简化版）可能长这样：
| 被依赖方\依赖方 | 用户服务 | 订单服务 | 支付服务 | 风控服务 | 消息服务 |
|---|---|---|---|---|---|
| 用户服务 | / | 有依赖 | 无 | 无 | 无 |
| 订单服务 | 无 | / | 有依赖 | 有依赖 | 无 |
| 支付服务 | 无 | 无 | / | 有依赖 | 有依赖 |
| 风控服务 | 有依赖 | 无 | 无 | / | 无 |
| 消息服务 | 无 | 无 | 无 | 无 | / |
每次做矩阵时，我会问三个问题：
- 有没有不该出现的依赖？（比如消息服务如果被支付服务依赖，说明消息服务可能是公共能力，需要确认定位）
- 有没有明显的“依赖黑洞”？（某一行绝大多数格子都是“有依赖”，说明大家都在依赖它，这个被依赖方必须足够稳定）
- 有没有循环路径？（矩阵转置后还能找到返回路径的就是潜在循环点）
这个矩阵不需要构建专门的系统，维护一个简单的表格都行，关键是定期做、每次都拉上核心开发一起看。很多架构隐患就是这么谈出来的，比看代码快得多。
4.3 架构评审与依赖预算：人机结合的最佳姿势
自动化工具能拦截明确违反规则的代码，但它判断不了“模块A对模块B的依赖是否合理”。这是架构评审的活。
我推荐在团队里引入“依赖影响评审”机制：凡是跨模块调用接口，必须在 MR 描述里写清楚“为什么需要跨模块”，评审人重点关注是不是有更内聚的归属地。人手紧的时候，至少保证核心模块（支付、风控、订单这类）的每一次跨模块变更都要过架构评审。
另外，我实践过“依赖预算”这个思路，非常简单有效：给每个模块设置一个“允许依赖的外部模块数量上限”。比如核心业务模块最多只允许依赖 5 个外部模块，如果一定要超过，必须在上线会议上说明理由并由架构责任人签字。这个“限额”会让团队主动收敛依赖，而不是放任依赖蔓延。
5. 一次重构实例：从依赖泥潭到清晰边界的完整过程
理论和工具聊了这么多，还是得来点实战复盘。我接手过一个积分商城系统，规模不大，但模块边界极其混乱。当时的主要痛点有四个：积分模块的领域对象被优惠券模块直接拿着改；抽奖模块和任务模块相互循环依赖；用户模块变成垃圾桶，什么都要往里塞；底层公共模块里堆着各种业务私有的工具方法。
5.1 阶段一：画现状反应图，找最大病灶
第一步不是改代码，而是把现状铺到桌面上。我用依赖分析工具生成了一份完整的模块依赖关系图，一眼就看出两个核心问题：积分模块被至少 4 个模块直接依赖，但积分模块又依赖了其中 3 个模块的领域对象，循环依赖几乎是成片的；抽奖和任务两个模块的循环依赖形成一个死结，谁都不愿意先松手。
我把这些依赖关系按“合理依赖”“可接受依赖”“危险依赖”三级分类，列成表格，定出了重构优先级：先拆最大的循环依赖环，再清理“模块依赖底层公用工具”的反向依赖，最后才处理泛化的用户模块拆分。
5.2 阶段二：接口抽取——用抽象切断物理循环
处理抽奖和任务的循环依赖时，我做了两件事：先在抽奖模块里声明了一个TaskConditionProvider接口，该接口只定义“判断用户是否完成指定任务”这一个方法；然后在任务模块里实现这个接口，但实现代码被注册到抽奖模块的配置工厂里。
这意味着抽奖模块的代码在编译层面完全不依赖任务模块的任何一个类，它只依赖自己定义的那个接口。任务模块通过配置装配注入实现，两个模块之间不再有代码层面的循环依赖链。上线后的表现很直观：抽奖模块和任务模块可以独立发布、独立测试，回归成本大幅下降。
5.3 阶段三：公共模块瘦身，把狗皮膏药撕掉
公库模块的问题最隐蔽——每个业务模块都会依赖它，导致公库模块被视为“放啥都合理”的地方。我看到过项目里公库模块存着“订单超时时间的常量”“根据用户等级计算折扣的工具类”这种业务私有逻辑。这表面上让依赖好写，实际上把业务逻辑打散到了公共模块，业务模块的完整性被破坏了，而且公库模块会因为承载太多职责而频繁变化，牵一发动全身。
治理方式是“业务归位”：把凡是跟具体业务能力挂钩的类和方法，一律下沉到对应的业务模块内；公库模块只保留真正的通用能力（日期处理、序列化、拦截器、字符串工具等）。这个过程被同事吐槽是“给公库减肥”，但减完肥之后，公库模块的变更频率骤降，各业务模块反而稳定了。
5.4 阶段四：补上自动化护栏，防止死灰复燃
重构完成不代表结束，因为业务还在发展，新人还会加入，依赖关系迟早会再次恶化。我在收尾阶段为项目补齐了 ArchUnit 架构测试用例，并允许 CI 强制执行。关键的用例包括：
- 公库模块禁止依赖任何业务模块
- 积分模块的内部实现类禁止被业务模块直接引用，业务模块只能依赖积分模块对外接口
- 所有业务模块的顶层 package 之间禁止出现循环依赖
在这些测试上线后的两个月里，新增的依赖违规都会被 MR 进程直接拦住。团队从“每次架构 review 靠嘴说”进化到了“不合格代码根本进不了主干”，这是架构治理真正意义上的落地。
6. 常见陷阱与我的避坑经验
模块划分和依赖管理没有银弹，每个项目语境不同，踩坑才是常态。以下四个坑是我在不同项目里反复遇到过的，拿出来分享，希望你能直接绕开。
6.1 过度设计：模块拆分比业务还复杂
有的团队为了模块化而模块化，项目还在雏形阶段就拆出十几个模块，每个模块只有几个类，接口定义却一堆。结果是花了大量精力在管理模块之间的依赖和沟通，业务功能进展缓慢。
我的判断标准是：少于三个稳定业务边界时，不需要过度模块化；模块边界应该由业务复杂度驱动，而不是由代码洁癖驱动。从两个大模块开始演进，比一开始拆出十个“精致”的小模块要实用得多。
6.2 公共模块当垃圾堆：一切为了“复用”
很多工程师有一个心理误区：“这段代码我在两个模块里都用到了，所以必须抽到 common 模块里复用。”这句话看似合理，实则危险。因为如果你抽取的是业务逻辑上的相似代码，而不是底层通用能力，你等于在把两个业务模块的耦合通过公共模块偷偷建立起来。
正确的做法是：如果两段业务代码单纯长得像，优先评估它们能否合并到同一个业务模块；如果不能，宁可暂时写一次重复实现，也不要把业务私有的东西塞进 common。短暂的重复好过长期的错误耦合。
6.3 只画边界不做守卫：架构文档沦为废纸
我见过不少团队花一两周时间画了漂亮的架构图和依赖规范文档，结果一次代码评审都没有严格执行过，最后文档成了摆设。架构治理必须自动化和制度并行，自动化拦截是底线，制度评审是防线。
我自己的底线是：任何核心模块的跨模块调用变更，都必须过架构评审；不合格的 MR 直接在 CI 拦截，不给人留“这次先这样，以后再说”的余地。宁可慢一点，也不能让依赖腐化的基因重新扩散。
6.4 无视模块的“变更耦合”：错把相似当内聚
还有一类问题是把“互为邻居”误判成“应该合并”。比如订单模块和支付模块，它们经常一起出现在下单流程里，看起来关系紧密，但它们的业务目标不同，变化原因不同——订单关心业务履约，支付关心资金安全。如果因为“经常一起改”就把它们合并，以后资金合规改动会污染整个订单流程。
我判断“是否该合并”的标准依然是变化原因：两个模块如果总是因为同一个需求一起变化，合并是合理的；如果只是因为一个流程上的先后关系而“经常一起出现”，不该合并，而应该通过定义清晰的接口来协作。
7. 一个可复用的模块划分与依赖管理落地流程
如果你看完前面内容觉得“有道理但不知从何下手”，这里整理一份可以直接照做的落地操作清单。这套流程我在多个项目里验证过，从零开始设计新系统，或者重构老系统，都能套用。
7.1 面向新系统的流程
如果是新系统，按顺序做五件事：
- 跟产品和业务痛点对齐，圈出至少三个核心业务能力边界，作为初始模块集合。
- 给每个模块写一句职责描述，用“本模块负责……，不负责……”的句式，能写清楚的留下，写不清的继续拆分或重命名。
- 画出预期依赖视图：模块间的箭头是单向的，没有环路；底层稳定模块才能被高层依赖。
- 用架构测试工具把关键规则固化成测试代码。
- 每次迭代开始时重新审视一次模块边界，需求变化是否导致某个模块已经“配不上”当前职责了。
7.2 面向存量系统的流程
存量系统大多已经长乱，直接推倒重来的风险极大，我的建议是从现状依赖图出发，进行“定点手术”：
- 用工具生成依赖图，给每个模块标注“被依赖数量”和“依赖数量”。
- 找出“被依赖数量最多”且“经常变更”的模块，这类模块是最大的风险点，优先治理。
- 对目标模块做依赖倒置改造：对外依赖一律改为接口依赖，内部实现不再泄漏给调用方。
- 每完成一个模块的改造，跑一次全量架构测试，同时记录模块的“依赖违规数量”，用曲线跟踪趋势。
- 全部改造完成之后，再回过头来补一轮“公共模块瘦身”，把业务私有逻辑下沉归位。
这个流程的核心是“逐模块击破，而不是一次性大爆炸重构”。我在实际项目中用这种方式处理过一个十分混乱的支付网关系统，花了大概三个月，在不冻结业务的前提下逐步完成了模块边界治理，期间没有一次发布事故。
7.3 团队协作规范：真正让模块划分存活下来的关键
最后必须强调一点：任何模块划分方案和依赖规则，想要持续生效，一定要变成团队共同认可的协作规范。我推荐开工前和组员一起拉一个简短的“依赖关系契约”，内容包括：
- 公共模块的所有权归谁，谁可以往 common 里加类
- 跨模块引用走什么方式
- 依赖检查用什么工具
- 违规如何处理
这个契约定稿后，不是靠记性，而是写进 README 和贡献指南里。新人入职第一周就会在 MR 上被自动拦截教育，比老员工花两小时讲课管用得多。
模块划分和依赖管理这门手艺，掌握起来不难，持续做好很难。它没有一劳永逸的完美方案，但有可持续演进的正确方向。希望这篇内容能帮你少走几段弯路。
