Gradle多项目构建核心是模块“有身份、有规矩、有来往”：settings.gradle注册身份（路径严格匹配、大小写敏感、禁通配符、显式声明根名），根build.gradle定规矩（subprojects统一Java环境、allprojects配仓库插件、禁直接写依赖），子模块build.gradle只选插件和声明依赖（路径一致、区分implementation/api），统一版本用libs.versions.toml。
Java 中用 Gradle 做多项目构建，关键不是堆模块，而是让每个模块“有身份、有规矩、有来往”：身份靠 settings.gradle 注册，规矩靠根 build.gradle 统一立，来往靠 project(':xxx') 显式声明。
settings.gradle 必须写对，否则 Gradle 根本不认识你的模块
这个文件是整个多项目构建的起点，必须放在根目录，且内容要严格匹配实际文件夹结构：
-
用相对路径 + 冒号语法：如子模块在
auth-service/目录下，就写include "auth-service"；若在infrastructure/discovery-client/，则写include "infrastructure:discovery-client" -
大小写敏感、不能带斜杠或后缀：
include "UserService"（错，文件夹叫user-service）或include "user-service/"（错，结尾不能有斜杠）都会导致Project directory '...' does not exist -
禁止通配符：
include "services/*"不被 Gradle 原生支持，会导致构建不稳定，必须逐个写明 -
根项目名建议显式声明：加上
rootProject.name = "my-platform"，避免默认名干扰发布或 IDE 识别
根 build.gradle 只管“定调子”，不写具体业务逻辑
它负责统一基础能力，所有子模块自动继承或按需复用：
-
用
subprojects统一 Java 环境：设置 JDK 版本、源码编码、测试框架等，例如：subprojects { java.toolchain.languageVersion = JavaLanguageVersion.of(17) } -
用
allprojects配置全局仓库和插件：比如启用java-library插件、配置阿里云镜像仓库，避免每个模块重复写repositories -
不直接写依赖：根项目的
dependencies块对子模块无效；想统一管理版本，请用libs.versions.toml或 Spring Boot 的 BOM
子模块 build.gradle 只做两件事：选插件、声明依赖
每个模块职责不同，配置应差异化，而不是复制粘贴：
立即学习“Java免费学习笔记（深入）”；
-
公共模块（如
common）只加依赖，不加 Spring Boot 插件：它只是工具集合，不应启动 Web 容器 -
服务模块（如
order-service）才应用org.springframework.boot:spring-boot-gradle-plugin，并声明implementation project(":common") -
依赖路径必须与
settings.gradle里完全一致：如果settings.gradle写了include "gateway"，那其他模块只能写project(":gateway")，写成project(":api-gateway")就会报Could not resolve project ':xxx' -
区分
implementation和api：内部用implementation；若该模块对外暴露接口（如 SDK 模块），用api project(":core")让上层能间接访问其依赖
统一版本管理别靠人肉改，用 libs.versions.toml
这是 Gradle 官方推荐、类型安全、IDE 支持好的方式，适合所有 Java 多模块项目：
- 在根目录创建
gradle/libs.versions.toml，定义版本别名和依赖坐标，例如：[versions]<br>springs = "3.3.2"<br>[libraries]<br>spring-web = { group = "org.springframework.boot", name = "spring-boot-starter-web", version.ref = "springs" } - 在子模块中直接引用：
implementation(libs.spring.web) - 升级时只需改 toml 文件里的
[versions]，所有模块自动同步，无需遍历修改几十个build.gradle
