Gradle单模块转多模块核心是确保settings.gradle显式include新模块(如include(":core", ":api")),子模块用implementation(project(":module"))声明依赖,严格隔离api/implementation边界,避免循环依赖与源码路径混用。

直接拆,但别一上来就建十个模块。Gradle单模块项目转多模块,核心不是“怎么建”,而是“拆完能不能编译通过、改一个地方要不要全量重编、依赖会不会传错”。很多团队拆完发现构建更慢、IDE卡顿、CI经常失败,问题基本都出在 settings.gradle 和子模块的 dependencies 声明上。
怎么让 settings.gradle 识别新模块
Gradle 不会自动扫描目录,必须显式声明。你新建了 core 和 api 目录,不加进 settings.gradle,它就只是文件夹,不是模块。
- 根目录的
settings.gradle必须包含include(":core", ":api"),路径用冒号开头,不能写成include("core")或include("./core") - 如果模块嵌套(比如
modules/user-service),写成include(":modules:user-service"),冒号是层级分隔符 - 模块名里不能有空格、下划线或点号,
:user_service合法,:user service或:user.service会报错Invalid project name - 执行
./gradlew projects可立刻验证是否识别成功——输出里没出现你的模块名,就是没生效
子模块 build.gradle 怎么写才不传错依赖
单模块里所有 implementation 都堆在根 build.gradle,一拆就容易漏掉关键约束。重点不是“加依赖”,而是“控制谁能看到谁”。
- 基础工具模块(如
:core)应该只用api暴露真正要被其他模块调用的类,内部工具类用implementation封装住,否则下游模块会意外继承不该用的 transitive 依赖 - 业务模块(如
:order)依赖:core,必须写成implementation(project(":core")),不能写成implementation("com.example:core:1.0.0")—— 后者走 Maven 仓库,绕过本地代码,改了:core的代码也不会触发:order重新编译 - Spring Boot 项目尤其注意:启动模块(
:app)要用implementation(project(":xxx")),但不能把spring-boot-starter-web这类 starter 放到:core里用api暴露,否则所有业务模块都会带上 Web 依赖,打出来的 jar 会异常臃肿
为什么改了一行代码,整个项目还在重编
这不是 Gradle 的锅,是模块边界没切对。Gradle 增量编译靠的是任务输入输出追踪,如果两个模块的源码目录混在一起、或者 sourceSets 配置错误,它就无法判断“改的是谁的代码”。
- 确认每个子模块的
src/main/java是独立路径,不要共用父项目的src目录;曾有人把:core的代码还留在根src下,只在build.gradle里改了sourceSets,结果 Gradle 根本没感知到变更来源 - 检查是否有跨模块的循环依赖:A 依赖 B,B 又依赖 A —— Gradle 会静默失败,表现为某些模块编译跳过、运行时报
NoClassDefFoundError,用./gradlew dependencies --configuration runtimeClasspath可查依赖图 - 禁用
configureondemand(Gradle 8.0+ 默认开启)有时反而能暴露真实问题:在gradle.properties加org.gradle.configuration-cache=false和org.gradle.configureondemand=false,看构建日志里哪些模块被强制重配置
最常被忽略的一点:模块拆完后,gradle.properties 里的版本变量(比如 springBootVersion=3.3.0)必须统一挪到根 build.gradle 的 ext 或 Version Catalog(gradle/libs.versions.toml),否则子模块各自读自己的 gradle.properties,版本一升级就满屏 red line。


















