1. 理解多模块项目的核心价值

在进入 Gradle 多模块配置的具体技术实现之前，你首先需要清晰地回答一个问题：为什么要把一个应用拆成多个模块？ 很多团队在项目初期为了快速上线，选择单模块（单体）结构。随着功能膨胀和团队扩张，单模块的“技术债”会以指数级速度侵蚀开发效率。本章将从单模块的典型痛点出发，对比模块化拆分带来的本质收益，并明确何时应该拥抱多模块架构。

1.1 单模块的三大典型痛点

假设你正在维护一个典型的电商后端项目，所有代码、配置、资源文件都集中在一个模块中。随着迭代推进，你会频繁遭遇以下问题：

痛点	具体表现	对团队的直接影响
构建速度衰退	每次改动任何一行业务代码或依赖版本，Gradle 都需要重新编译整个项目中的大部分类。编译、测试、静态检查全量执行。	开发者每日等待构建的时间从 30 秒增长到 5~10 分钟。CI 流水线阻塞严重，部署频率被迫降低。
职责边界模糊	订单服务直接修改用户服务的 DAO 层代码；支付模块与优惠券模块共享同一个数据库连接池 Bean。没有强制隔离机制。	随意的跨层调用导致循环依赖频繁出现；日常 Merge Request 中反复出现“不应该改这里”的代码审查意见。
团队协作冲突	5 个团队在同一个 Git 仓库、同一个 Gradle 工程中开发。每次提交都可能因为公共资源的并发修改导致冲突。	解决合并冲突消耗的时间超过了实际编码时间；发布前需要所有团队同时冻结代码，版本管理基本靠人工协调。

1.2 模块化拆分带来的核心收益

将单模块拆分为多个物理上独立的子模块，每个子模块有明确的职责边界、独立的构建配置和版本演进周期。这种架构调整带来的不仅仅是代码组织上的整洁，更是团队协作模式与构建效率的质变：

• 增量构建与并行构建： Gradle 可以精确识别哪些模块的输入没有发生变化，只重新编译受影响的模块；同时，无依赖关系的模块可以在不同线程上并行编译，将整体构建时间压缩到原来的 20%~30%。
• 强制依赖隔离： 子模块只能访问其显式声明的依赖项，任何跨模块的“偷懒调用”都会在编译期被拦截，从根本上消除循环依赖和隐式耦合。
• 独立演进与发布： 核心库模块（如 common、storage）可以独立升级版本，业务模块按需选择依赖版本；支持按模块进行灰度发布和独立回滚。

1.3 多模块项目的适用场景判断

并非所有项目都需要立即切换到多模块结构。下表中的场景可以帮助你做出务实判断：

判断维度	适合单模块	适合多模块
团队规模	1~3 人，职责覆盖全栈	5 人以上，有明确的分工边界（如支付组、用户组）
代码规模	总代码量 < 5万行，源文件 < 200	总代码量 > 10万行，源文件 > 500
构建时间	全量构建 < 90 秒	全量构建 > 5 分钟
业务复杂性	单一业务流程，极少跨域调用	多域业务（如交易、营销、风控），存在明显的分层抽象需求
版本管理策略	统一发布、统一回滚	需要组件级独立版本、按模块灰度

1.4 从单模块到多模块的架构演变示意图

下面的 SVG 图清晰展示了单模块架构与多模块架构的核心差异。左侧的单模块将所有代码混在一起，任何一个编译单元的变化都可能触发全局重编译；右侧的多模块架构通过明确的模块边界和依赖声明，实现了局部增量编译、并行构建和职责隔离。

1.5 模块化拆分的核心原则

结合上述对比，在正式开始 Gradle 多模块配置之前，请记住以下四条原则，它们将贯穿后续所有章节：

1. 单一职责： 每个模块只承载一个清晰的业务域或技术域。一个模块如果同时负责“订单处理”和“支付回调校验”，说明拆分粒度还不够细。
2. 依赖方向一致： 依赖关系应该形成有向无环图（DAG）。业务模块依赖技术模块，技术模块绝不反向依赖业务模块。
3. 接口优先于实现： 模块间的通信优先通过 API 接口模块进行，而不是直接引用实现类的具体包。这为后续的独立演进和 Mock 测试提供了基础。
4. 构建隔离： 每个模块的 build.gradle 只声明它所需要的直接依赖，不继承父项目的依赖传递。显式依赖是 Gradle 执行增量构建和并行构建的前提条件。