构建与依赖 / 系统课时
使用 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 的强制要求,团队应按实际运行环境调整。
<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>配置保存后执行:
mvn validate预期输出:环境和依赖都满足规则时,构建完成并出现成功标记;耗时等动态信息会因机器不同而变化。
[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> 中。
<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 而被真正解决。