Java 项目构建选型：Maven、Gradle 与模块化实践

学完这篇，你能在半小时内为自己的 Java 项目选对 Maven 或 Gradle，并把单模块工程拆成能编译、能复用、不踩循环依赖坑的多模块结构。

第一步：先分清你的项目属于哪一类

选型不是比谁先进，而是比谁匹配：

• 公司内部服务、团队 Java 版本统一、CI 流程固定 → Maven，声明式、报错好查、新人零学习成本。
• 单体仓库、模块多、要求增量构建和构建缓存（Android、Kotlin、大型微服务群）→ Gradle。
• 需要 JDK 9+ 的模块化（JPMS）或 jlink 裁剪运行时 → 两者都能做，但 Gradle 对 module path 的处理更省心。

注意：不要用「Gradle 比 Maven 快」当唯一理由。小项目两者差距在秒级，而 Gradle 的构建脚本是代码，出错时排查成本更高。

第二步：Maven 的最小可用多模块骨架

根 `pom.xml` 用 `pom` 打包，只做聚合和版本管理：

<packaging>pom</packaging>
<modules>
  <module>common</module>
  <module>service</module>
  <module>web</module>
</modules>
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.demo</groupId>
      <artifactId>common</artifactId>
      <version>${project.version}</version>
    </dependency>
  </dependencies>
</dependencyManagement>

子模块里引用兄弟模块时不要写版本号，交给 `dependencyManagement` 统一。常用命令：

mvn -T 1C clean install          # 并行构建（1 线程/核）
mvn -pl web -am package          # 只构建 web 及其依赖的模块
mvn dependency:tree -Dincludes=com.demo

注意：子模块继承父 POM 靠 `<parent>` 的 `relativePath`，默认 `../pom.xml`。如果目录层级不是标准的，必须显式写对，否则会去本地仓库找父 POM 然后报「找不到」。

第三步：Gradle 的最小可用多模块骨架

`settings.gradle.kts` 声明模块：

rootProject.name = "demo"
include("common", "service", "web")

根 `build.gradle.kts` 用 `subprojects` 或 `allprojects` 统一插件和 Java 版本，子模块只声明自己的依赖：

plugins { java }
java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }
dependencies {
  implementation(project(":common"))   // 不对外暴露
  api(project(":service"))             // 对外暴露
}

命令用 Wrapper，别用本机 gradle：

./gradlew :web:build --configuration-cache
./gradlew dependencies --configuration runtimeClasspath

版本统一建议用 Version Catalog（`gradle/libs.versions.toml`），比在根脚本里拼变量好维护。

注意：`implementation` 和 `api` 的区别直接决定依赖是否传递。选错会导致「本地能编译、CI 编译不过」——因为 CI 是干净构建，缺的传递依赖才暴露出来。

第四步：多模块拆分与 JPMS 落地

拆模块只守一条规则：依赖方向单向，不允许环。常见分层是 `common`（工具与 DTO）→ `service`（业务）→ `web`（控制器与启动类）。发现 A 依赖 B、B 又依赖 A 时，把共用部分下沉到 `common`，而不是互相引用。

要真正用 JPMS，在 `src/main/java` 根目录放 `module-info.java`：

module com.demo.common {
    exports com.demo.common.api;        // 只导出对外 API
    requires transitive java.logging;   // 传递依赖
    opens com.demo.common.entity to com.fasterxml.jackson.databind; // 反射框架需要
}

Gradle 中 `java.modularity.inferModulePath` 默认开启，模块化项目会自动走 module path；Maven 用 `maven-compiler-plugin` 即可，模块描述符放在各模块源码根。

注意：Spring Boot 的可执行 fat jar 与 JPMS 不兼容——`module-info.java` 会和 Boot 的类加载器冲突。用 Boot 打包就别加模块描述符，把模块化留给内部库；真要做模块化运行时，考虑用 jlink 自己组装。

校验依赖是否合理：

jdeps --module-path build/libs --print-module-deps com.demo.web

第五步：构建速度与依赖治理

Maven 侧：`mvn -T 1C` 并行、`-o` 离线、避免 `install` 跑全量，CI 上用 `-pl ... -am` 只构建受影响模块。

Gradle 侧：开构建缓存（`org.gradle.caching=true`）、配置缓存（`--configuration-cache`）、`--build-cache` 复用他人产物；少用 `allprojects`，它会让配置阶段无法缓存。

两者都要做版本收敛：Maven 用 BOM（`<scope>import</scope>`）统一第三方版本，Gradle 用 `platform()` 引 BOM。别再靠 `exclusions` 一个个排除冲突。

小结

• 选型看项目形态：标准化团队选 Maven，重增量与缓存选 Gradle，别看热闹。
• 多模块靠父 POM 的 `dependencyManagement` 或 Gradle 的 Version Catalog 统一版本，子模块不写版本号。
• 模块拆分守单向依赖，环依赖只能靠下沉共用代码解决。
• Gradle 里分清 `implementation` 与 `api`，Maven 里善用 `-pl -am` 增量构建。
• 用 Spring Boot fat jar 时不要加 `module-info.java`，模块化留给内部库或 jlink 场景。