构建与依赖 / 系统课时

使用 Enforcer 约束构建环境

使用 Enforcer 约束构建环境

同一份项目在不同电脑上“有人能构建、有人不能构建”,通常不是代码本身的问题,而是 Maven、JDK 或依赖图不一致。Enforcer 可以把这些约束写进 pom.xml,在构建早期直接失败,让本地与 CI 使用同一套可检查规则。

学习目标

  • 用 Enforcer 校验 Maven 与 JDK 版本范围。
  • 用 dependencyConvergence 发现依赖版本分叉,用 bannedDependencies 阻止明确禁用的库。
  • 能根据失败规则定位环境或依赖问题,而不是靠换电脑、删缓存碰运气。

在 validate 阶段拦截不兼容环境

下面示例给出一套可直接运行的团队基线:Maven 允许 3.9.6 到 4.0.0 之前的版本,JDK 允许 17~21,构建还必须满足依赖收敛,并禁止引入 commons-logging 与旧的 log4j:log4j。这里的版本范围是示例策略,不是 Maven 的强制要求,团队应按实际运行环境调整。

xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>enforcer-demo</artifactId>
  <version>1.0.0</version>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-enforcer-plugin</artifactId>
        <version>3.6.2</version>
        <executions>
          <execution>
            <id>enforce-build-environment</id>
            <phase>validate</phase>
            <goals>
              <goal>enforce</goal>
            </goals>
            <configuration>
              <fail>true</fail>
              <rules>
                <requireMavenVersion>
                  <version>[3.9.6,4.0.0)</version>
                </requireMavenVersion>
                <requireJavaVersion>
                  <version>[17,22)</version>
                </requireJavaVersion>
                <dependencyConvergence/>
                <bannedDependencies>
                  <excludes>
                    <exclude>commons-logging:commons-logging</exclude>
                    <exclude>log4j:log4j</exclude>
                  </excludes>
                  <searchTransitive>true</searchTransitive>
                  <message>项目禁止使用已列入黑名单的依赖,请替换后再构建。</message>
                </bannedDependencies>
              </rules>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

配置保存后执行:

bash
mvn validate

预期输出:环境和依赖都满足规则时,构建完成并出现成功标记;耗时等动态信息会因机器不同而变化。

text
[INFO] BUILD SUCCESS

分清依赖收敛和禁止依赖

dependencyConvergence 解决“同一个坐标出现多个版本”的问题。例如模块 A 间接带入 commons-codec:1.15,模块 B 又带入 commons-codec:1.17.0,即使 Maven 最终只选一个版本,Enforcer 仍会把这种分叉视为风险。正确修法通常是在 dependencyManagement 中统一版本,并确认调用方都兼容该版本。

bannedDependencies 解决的是另一类问题:某个坐标无论只有一个版本还是多个版本,都不允许进入依赖图。上面的 searchTransitive=true 会连传递依赖一起检查,所以“我没有直接写这个依赖”并不能绕过规则。

规则 检查对象 典型失败 常见修复
requireMavenVersion Maven 运行时 开发机仍使用 3.8.x 升级 Maven,或按团队基线调整范围
requireJavaVersion 当前 JDK CI 用 JDK 11,本地用 JDK 17 统一 Toolchain、CI 镜像或 JAVA_HOME
dependencyConvergence 完整依赖图 同一组件出现 1.15 与 1.17.0 用 dependencyManagement 统一并回归测试
bannedDependencies 直接与传递依赖 黑名单组件被第三方库带入 升级上游依赖或使用 exclusions 排除

验证禁止依赖规则是否真的生效

不要只确认插件“配置过”,还要故意制造一次失败。可以临时向示例 POM 加入下面依赖,验证 bannedDependencies 会阻止构建;验证完成后再删除。下面是片段示例,需要放在 <project> 的 <dependencies> 中。

xml
<dependency>
  <groupId>commons-logging</groupId>
  <artifactId>commons-logging</artifactId>
  <version>1.2</version>
</dependency>

再次执行 mvn validate 时,预期结果是构建以非零退出码失败,并在 Enforcer 错误信息中指出黑名单依赖 commons-logging:commons-logging。删除该依赖后重新执行,结果应恢复为 BUILD SUCCESS。

按失败规则定位而不是盲目清缓存

版本规则失败时先检查当前命令实际使用的运行时,而不是 IDE 设置页;依赖规则失败时则检查“谁把冲突带进来”。环境问题常见于终端和 IDE 使用不同 JAVA_HOME,依赖问题常见于升级某个框架后新增传递依赖。两类问题的修复路径完全不同。

排查依赖收敛时,优先读取 Enforcer 报错中列出的两条依赖路径,再决定是在 dependencyManagement 统一版本,还是在上游依赖上加 exclusions。只有确认仓库缓存损坏时才清理本地仓库;版本不满足、依赖冲突或黑名单命中都不会因为删除 .m2 而被真正解决。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Enforcer 约束构建环境

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通