第4章 版本目录与平台：Version Catalog 声明、BOM 平台依赖、统一版本管理

4.1 版本管理的三个核心维度

在多模块 Gradle 工程中，依赖版本分散、重复声明、升级困难是团队协作的主要痛点。本章聚焦三个递进的控制手段：Version Catalog（版本目录）作为版本声明的标准化契约；BOM（Bill of Materials）作为平台级依赖对齐的行业惯例；统一版本管理作为工程落地的最终目标。三者共同构成从“单点声明”到“全局可观测”的版本治理链路。

4.2 Version Catalog 声明与结构

Catalog 使用 TOML 格式，将版本号、依赖坐标、插件声明集中到单一文件中。Gradle 7.0+ 原生支持，无需额外插件。

4.2.1 libs.versions.toml 标准骨架

[versions]
kotlin = "1.9.22"
coroutines = "1.8.0"
springBoot = "3.2.5"

[libraries]
kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }
kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "springBoot" }

[bundles]
kotlin-common = ["kotlin-stdlib", "kotlinx-coroutines-core"]

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
spring-boot = { id = "org.springframework.boot", version.ref = "springBoot" }

4.2.2 在 build.gradle.kts 中消费 Catalog

dependencies {
    // 通过类型安全访问器引用
    implementation(libs.kotlin.stdlib)
    implementation(libs.kotlinx.coroutines.core)
    implementation(libs.spring.boot.starter.web)

    // 引用 bundle
    implementation(libs.bundles.kotlin.common)
}

plugins {
    alias(libs.plugins.kotlin.jvm)
    alias(libs.plugins.spring.boot)
}

4.3 BOM 平台依赖机制

BOM（Bill of Materials）是 Maven/Gradle 生态中用于集中控制一组依赖版本的标准契约。它在 dependencyManagement 块中声明，不会直接将依赖添加到编译路径，仅做版本锁定的“锚点”。

4.3.1 声明 BOM 平台

// 使用 platform() 引入 BOM，不传递 transitive 依赖
implementation(platform("org.springframework.boot:spring-boot-dependencies:3.2.5"))

// 强制覆盖 BOM 中定义的版本（慎用）
implementation(enforcedPlatform("org.springframework.boot:spring-boot-dependencies:3.2.5"))

// 在 Catalog 中声明 BOM
[libraries]
spring-boot-bom = { module = "org.springframework.boot:spring-boot-dependencies", version.ref = "springBoot" }

4.3.2 BOM 与 Catalog 协同工作

// 在子模块中同时使用 Catalog 和 BOM
dependencies {
    // BOM 锁定版本平台
    implementation(platform(libs.spring.boot.bom))

    // 具体依赖可以省略版本号（由 BOM 提供）
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")

    // 也可混合使用 Catalog 中声明的非 BOM 依赖
    implementation(libs.kotlinx.coroutines.core)
}

4.4 统一版本管理架构

将 Version Catalog 的外部声明能力与 BOM 的平台对齐能力组合，形成“Catalog 收口 + BOM 对齐 + 约束校验”的三层治理体系。

4.4.1 三层治理模型

• 层1 — Catalog 版本池： 在 libs.versions.toml 中维护所有可用的版本号，作为单一数据源。
• 层2 — BOM 平台锚： 通过 platform() 引入框架级 BOM，保证同组依赖版本兼容。
• 层3 — 约束强制： 使用 DependencyConstraint 或 strictly 声明跨模块的必须版本范围。

// 在根项目的 build.gradle.kts 中定义全局约束
dependencyConstraints {
    implementation("com.fasterxml.jackson:jackson-bom:2.17.1") {
        because("统一 Jackson 版本以避免运行时序列化冲突")
    }
}

// 在子模块中强制校验
configurations.all {
    resolutionStrategy {
        failOnVersionConflict()
        preferProjectModules()
    }
}

4.4.2 依赖锁定（Lock State）

// 启用依赖锁定文件（gradle.lockfile）
dependencyLocking {
    lockAllConfigurations()
    lockMode = LockMode.STRICT
}

// 命令行更新锁文件
./gradlew dependencies --update-locks

// 在 CI 中校验锁文件是否与当前依赖一致
./gradlew dependencies --lock-file gradle.lockfile

4.5 章节核心流程：统一版本管理链路

下图展示了从 Catalog 声明 → BOM 平台引入 → 子项目版本对齐的完整链路，以及约束校验和锁文件在其中的作用位置。

4.6 调试方法与常见错误

4.6.1 诊断 Catalog 解析结果

// 查看 Catalog 生成的访问器列表
./gradlew libsVersions

// 输出当前工程所有依赖及版本来源
./gradlew dependencies --configuration compileClasspath

// 查看特定模块的版本冲突报告
./gradlew :module-a:dependencyInsight --dependency jackson-databind --configuration runtimeClasspath

4.6.2 典型错误与修复

4.7 性能优化与部署策略

4.7.1 增量编译与 Catalog 缓存

// gradle.properties 中启用依赖缓存
org.gradle.caching=true
org.gradle.parallel=true

// Catalog 文件的变更会自动触发增量重新解析
// 建议将 libs.versions.toml 纳入 Git 版本管理

4.7.2 多项目共享 Catalog 的推荐布局

# 在根项目 gradle/ 目录下统一维护
gradle/
├── libs.versions.toml          # 主版本目录
├── libs.plugins.toml           # 可选：分离插件声明
└── libs.bundles.toml           # 可选：分离依赖组

# 在 settings.gradle.kts 中引入
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
}

4.7.3 性能关键指标参考

4.8 本章小结

Version Catalog 提供了类型安全、集中声明的版本池；BOM 平台借助 Maven 生态的 Bill of Materials 实现了框架级依赖对齐；将二者与依赖锁定、约束校验组合，即可构建可观测、可追溯的统一版本管理体系。下一阶段的重点是将这套机制与多仓库、复合构建（Composite Build）集成，实现跨项目的版本治理联邦。