Java工程实践中依赖管理工具 Maven 的使用与维护

关键词：Maven、依赖冲突、多模块、私服、CI/CD、版本策略、依赖树、BOM

一、为什么今天仍需深入 Maven

在 Gradle、Bazel 等“后浪”冲击下，Maven 依旧占据企业级 Java 项目 60% 以上份额。
Maven 的真正痛点不是“能不能跑”，而是“跑得健康”——依赖地狱、构建漂移、私服治理、CI 可重现性。
本文以 “可维护、可演进、可观测” 三大目标，贯穿一条从单模块 Demo 到千级 Jar 包大型系统的实战路径。

二、一个最小可运行示例：从 0 到 mvn package

2.1 目录结构

demo-parent
├── pom.xml
└── demo-service
    ├── pom.xml
    └── src/main/java/com/example/DemoApp.java

2.2 顶层父 POM：版本集中管控

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>demo-parent</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <!-- 所有子模块强制收敛的依赖版本 -->
    <spring-boot.version>3.2.5</spring-boot.version>
    <lombok.version>1.18.32</lombok.version>
  </properties>

  <dependencyManagement>
    <dependencies>
      <!-- Spring Boot BOM -->
      <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-dependencies</artifactId>
        <version>${spring-boot.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
</project>

2.3 子模块 POM：零版本号声明

<project>
  <parent>
    <groupId>com.example</groupId>
    <artifactId>demo-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>demo-service</artifactId>

  <dependencies>
    <!-- 直接使用 BOM 中定义的版本 -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <scope>provided</scope>
    </dependency>
  </dependencies>
</project>

2.4 构建验证

mvn -U clean package -pl demo-service -am
java -jar demo-service/target/demo-service-1.0.0-SNAPSHOT.jar

至此，我们已拥有 单一可信版本源（SSOT） 的雏形。

三、依赖冲突的 3 种定位与 4 种解决策略

3.1 如何一眼看穿冲突

mvn dependency:tree -Dverbose -Dincludes=commons-logging

典型输出片段：

[INFO] +- org.springframework:spring-core:jar:6.1.6:compile
[INFO] |  \- (commons-logging:commons-logging:jar:1.2:compile - omitted for conflict with 1.1.1)
[INFO] \- commons-logging:commons-logging:jar:1.1.1:compile

omitted for conflict 即 Maven 仲裁后被丢弃的版本。

3.2 策略 1：依赖调解规则（就近优先 + 声明优先）

无需额外配置，但无法解决语义不兼容的场景。

3.3 策略 2：<exclusions> 精准排除

<dependency>
  <groupId>org.apache.httpcomponents.client5</groupId>
  <artifactId>httpclient5</artifactId>
  <version>5.3</version>
  <exclusions>
    <exclusion>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-api</artifactId>
    </exclusion>
  </exclusions>
</dependency>

3.4 策略 3：<dependencyManagement> 强制版本

在父 POM 中统一定义，子模块不可覆盖。

3.5 策略 4：BOM + 自定义 Enforcer 规则

引入 extra-enforcer-rules 插件，在 CI 阶段阻断冲突。

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-enforcer-plugin</artifactId>
  <version>3.4.1</version>
  <executions>
    <execution>
      <goals><goal>enforce</goal></goals>
      <configuration>
        <rules>
          <banDuplicateClasses>
            <findAllDuplicates>true</findAllDuplicates>
          </banDuplicateClasses>
          <dependencyConvergence/>
        </rules>
      </configuration>
    </execution>
  </executions>
</plugin>

四、私服 Nexus3 的搭建与客户端镜像加速

4.1 Docker 单节点启动

docker run -d --name nexus \
  -p 8081:8081 \
  -v nexus-data:/nexus-data \
  sonatype/nexus3:3.68.1

默认管理员密码：cat /nexus-data/admin.password。

4.2 在 settings.xml 中配置镜像

<mirrors>
  <mirror>
    <id>nexus-central</id>
    <mirrorOf>central</mirrorOf>
    <url>http://nexus.example.com:8081/repository/maven-public/</url>
  </mirror>
</mirrors>

4.3 发布 SNAPSHOT 与 Release

mvn clean deploy -DskipTests

在 distributionManagement 节点指定仓库即可。

五、CI/CD 中的可重现构建

5.1 Maven 3.9+ 的 maven.build.timestamp 风险

默认 ${maven.build.timestamp} 每次都会变化，导致 jar 的 SHA 不一致。
解决：

<properties>
  <maven.build.timestamp.format>yyyy-MM-dd</maven.build.timestamp.format>
  <revision>1.0.0</revision>
</properties>
<build>
  <finalName>${project.artifactId}-${revision}</finalName>
</build>

5.2 使用 BuildKit + Maven 并行下载

Dockerfile 片段：

FROM maven:3.9.6-eclipse-temurin-17 AS build
WORKDIR /app
COPY pom.xml .
RUN mvn -B -e -T 1C dependency:go-offline
COPY src ./src
RUN mvn -B -e -T 1C package -DskipTests

六、多模块工程的分层依赖治理

6.1 典型四层架构

demo-parent
├── demo-api            // 纯接口，零依赖
├── demo-domain         // JPA 实体
├── demo-infra          // MyBatis、Redis 等
└── demo-web            // Spring Boot

6.2 使用 Maven Reactor 增量构建

mvn -T 1C -pl demo-web -am install

-am（also-make）自动构建上游依赖，避免“全量地狱”。

6.3 反向依赖检查

mvn dependency:analyze

输出 Unused declared dependencies 与 Used undeclared dependencies，提前发现“胖 jar”。

七、常见故障排查清单

八、小结与演进路线

1. 单仓库 → 多仓库：使用 Maven 3.9 的 repository 动态路由。
2. BOM → Bill of Materials：自定义企业级 BOM，版本策略遵循 CalVer（如 2025.07）。
3. Maven → Maven-Toolchain：在大型团队统一 JDK、工具链版本，避免“在我电脑能跑”。
4. 私服 → 云原生缓存：引入 BuildKit 的 RUN --mount=type=cache 与 maven.repo.local=/tmp/m2，加速 50%。