Java Gradle 版本目录 怎样处理

Java Gradle 项目里，依赖版本散落在多个 build.gradle 文件中，最容易出现的问题不是“不会写依赖”，而是同一个库在不同模块里各写了一遍，升级时漏改，或者以为版本目录已经统一了版本，实际解析结果仍被平台、约束或传递依赖影响。处理这类问题，建议把版本目录当作可复用的声明层，再用平台和约束完成真正的版本对齐。

官方地址：https://docs.gradle.org/current/userguide/version_catalogs.html

最稳妥的做法是把版本和坐标集中到 gradle/libs.versions.toml，在构建脚本中使用 libs 访问器；遇到一组库必须协同升级时，再叠加 BOM 或 Java Platform，遇到版本范围和拒绝规则时使用 dependency constraints。版本目录本身只负责命名与复用，不会自动替你解决全部冲突。

一、先把版本目录的职责分清

Version Catalog 适合保存版本号、模块坐标、插件坐标和常用依赖组合。它生成的是构建脚本可访问的类型安全别名，例如 libs.slf4j.api；它不会把所有传递依赖强行改成同一个版本，也不会替代 Gradle 的冲突选择规则。

二、创建默认的 libs.versions.toml

在项目根目录创建 gradle/libs.versions.toml。默认目录会被 Gradle 作为名为 libs 的版本目录读取。下面的示例把 Java 测试库、日志库和测试组合放在同一个地方，别名中的短横线会形成分层访问器。

[versions]
# 版本集中维护，升级时只改这一处
slf4j = "2.0.16"
junit = "5.11.3"

[libraries]
# module 保留 Maven 坐标，version.ref 引用上面的版本键
slf4j-api = { module = "org.slf4j:slf4j-api", version.ref = "slf4j" }
junit-bom = { module = "org.junit:junit-bom", version.ref = "junit" }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter" }

[bundles]
# bundle 只复用一组依赖，不改变它们的版本选择规则
test = ["junit-jupiter"]

这里的 junit-jupiter 没有单独写版本，是因为后面会先导入 JUnit BOM。若一个库不受平台管理，就应在目录里给它明确的 version.ref，不要依赖动态版本。

三、在 Java 构建脚本里使用类型安全别名

版本目录生成访问器后，Kotlin DSL 可以直接使用 libs.slf4j.api 和 libs.bundles.test。把坐标从构建脚本移走后，多模块工程中的依赖声明更容易保持一致。

plugins {
    java
}

repositories {
    // 依赖解析需要声明仓库，仓库地址不由版本目录决定
    mavenCentral()
}

dependencies {
    // 通过别名引用集中维护的坐标
    implementation(libs.slf4j.api)

    // 先导入 BOM，再使用由 BOM 管理版本的测试库
    testImplementation(platform(libs.junit.bom))
    testImplementation(libs.bundles.test)
}

tasks.test {
    // 使用 JUnit Platform 执行 JUnit 5 测试
    useJUnitPlatform()
}

如果使用 Groovy DSL，访问器写法会略有不同，但职责不变：implementation libs.slf4j.api 表示引用目录中的别名，不能把它误解成“锁定整个依赖图”。修改 TOML 后，先运行一次 Gradle 配置或任务，让访问器重新生成；别名拼写不对时，优先检查短横线对应的层级名称。

四、用平台和约束处理真正的版本选择

版本目录解决的是声明重复，平台或 BOM 解决的是一组模块的协同版本。比如 JUnit 的 BOM 可以让多个 JUnit 模块使用同一套兼容版本；如果团队还要限制某个传递依赖的最低版本或禁止一个已知问题版本，就需要约束。

dependencies {
    // platform 让同一 BOM 管理的模块共享版本
    testImplementation(platform(libs.junit.bom))
    testImplementation(libs.junit.jupiter)

    constraints {
        // 约束用于表达团队允许的版本范围
        implementation("com.fasterxml.jackson.core:jackson-databind") {
            version {
                strictly("2.18.2")
            }
            because("统一多模块服务的 JSON 解析版本")
        }
    }
}

不要把所有版本都写成 strictly。严格约束会减少 Gradle 的选择空间，也可能让插件或第三方平台升级时出现无法解析；只有当团队确实需要强边界时才使用。更常见的分工是：目录保存可读的版本名，BOM 管理同一生态，约束处理少数关键库的边界。

五、用依赖解析结果确认修改生效

当“版本目录怎样处理”具体变成“为什么改了版本仍没有变化”，不要只回看 TOML。先针对目标模块和配置查看依赖树，再用 dependencyInsight 追踪某个组件为什么被选中。

# 先看 testRuntimeClasspath 的完整解析结果
./gradlew :app:dependencies --configuration testRuntimeClasspath

# 再追踪某个模块的选择原因和候选版本
./gradlew :app:dependencyInsight \
  --dependency jackson-databind \
  --configuration runtimeClasspath

如果结果没有变化，按这个顺序排查：目标模块是否真的使用了 libs 别名；当前配置是否被另一个平台管理；依赖是否来自插件或约定插件；最后再看是否存在严格约束、强制版本或不同的变体选择。这样能把“目录没生效”和“目录生效但被更高优先级规则覆盖”区分开。

相关问题

版本目录能替代 dependency constraints 吗？

不能完全替代。目录主要提供集中声明和可读别名，约束表达的是版本选择条件，两者可以一起使用。

多个模块应该共用一个 libs.versions.toml 吗？

同一个 Gradle 构建中的模块通常共用默认目录；如果多个独立构建需要共享版本，可通过发布版本目录或约定插件复用，但要先明确更新边界。

为什么 TOML 里改了版本，依赖树仍然没变？

可能是目标配置没有消费该别名，也可能是 BOM、约束、插件或传递依赖选择了另一个版本。用 dependencyInsight 查看选择原因比盯着文件更快。