Gradle Dependency Management

Gradle依赖管理

Purpose

用途

Centralize and manage dependencies effectively across Gradle projects using version catalogs, BOMs, and dependency constraints. This skill helps you standardize versions, resolve conflicts, and maintain security across multi-module builds.

借助版本目录（version catalogs）、物料清单（BOMs）和依赖约束，在Gradle项目中高效地集中管理依赖。该技能可帮助你在多模块构建中标准化版本、解决冲突并保障安全性。

When to Use

适用场景

Use this skill when you need to:

Centralize dependency versions across multi-module projects
Create type-safe dependency references with version catalogs
Resolve dependency version conflicts
Enforce consistent dependency versions across a team
Integrate Spring Boot or GCP BOMs for curated dependency sets
Lock dependency versions for reproducible builds
Manage transitive dependencies with constraints

在以下场景中可使用该技能：

在多模块项目中集中管理依赖版本
通过版本目录创建类型安全的依赖引用
解决依赖版本冲突
在团队中强制统一依赖版本
集成Spring Boot或GCP BOM以使用经过筛选的依赖集
锁定依赖版本以实现可复现的构建
通过约束管理传递依赖

Quick Start

快速开始

Create a version catalog in

gradle/libs.versions.toml

:

toml

[versions]
spring-boot = "3.5.5"
junit = "5.11.0"

[libraries]
spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web" }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }

[bundles]
spring-boot-web = ["spring-boot-starter-web"]
testing = ["junit-jupiter"]

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

Configure in

settings.gradle.kts

:

kotlin

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
}

Use in

build.gradle.kts

:

kotlin

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

dependencies {
    implementation(libs.spring.boot.starter.web)
    testImplementation(libs.bundles.testing)
}

在

gradle/libs.versions.toml

中创建版本目录：

toml

[versions]
spring-boot = "3.5.5"
junit = "5.11.0"

[libraries]
spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web" }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }

[bundles]
spring-boot-web = ["spring-boot-starter-web"]
testing = ["junit-jupiter"]

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

在

settings.gradle.kts

中配置：

kotlin

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
}

在

build.gradle.kts

中使用：

kotlin

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

dependencies {
    implementation(libs.spring.boot.starter.web)
    testImplementation(libs.bundles.testing)
}

Instructions

操作步骤

Step 1: Set Up Version Catalog

步骤1：设置版本目录

Create

gradle/libs.versions.toml

with your project's dependencies:

toml

[versions]
spring-boot = "3.5.5"
spring-cloud = "2024.0.1"
spring-cloud-gcp = "6.1.1"
mapstruct = "1.6.3"
testcontainers = "1.21.0"
junit = "5.11.0"
mockito = "5.14.0"

[libraries]

创建

gradle/libs.versions.toml

文件并添加项目依赖：

toml

[versions]
spring-boot = "3.5.5"
spring-cloud = "2024.0.1"
spring-cloud-gcp = "6.1.1"
mapstruct = "1.6.3"
testcontainers = "1.21.0"
junit = "5.11.0"
mockito = "5.14.0"

[libraries]

Spring Boot

spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web" } spring-boot-starter-actuator = { module = "org.springframework.boot:spring-boot-starter-actuator" } spring-boot-starter-data-jpa = { module = "org.springframework.boot:spring-boot-starter-data-jpa" } spring-boot-starter-test = { module = "org.springframework.boot:spring-boot-starter-test" }

GCP

spring-cloud-gcp-starter = { module = "com.google.cloud:spring-cloud-gcp-starter" } spring-cloud-gcp-pubsub = { module = "com.google.cloud:spring-cloud-gcp-starter-pubsub" } google-cloud-secretmanager = { module = "com.google.cloud:google-cloud-secretmanager", version = "2.2.0" }

Database

数据库

postgresql = { module = "org.postgresql:postgresql" } flyway-core = { module = "org.flywaydb:flyway-core" }

MapStruct

mapstruct = { module = "org.mapstruct:mapstruct", version.ref = "mapstruct" } mapstruct-processor = { module = "org.mapstruct:mapstruct-processor", version.ref = "mapstruct" }

Testing

测试

junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" } mockito-core = { module = "org.mockito:mockito-core", version.ref = "mockito" } testcontainers-junit = { module = "org.testcontainers:junit-jupiter", version.ref = "testcontainers" } testcontainers-postgresql = { module = "org.testcontainers:postgresql", version.ref = "testcontainers" }

[bundles] spring-boot-web = ["spring-boot-starter-web", "spring-boot-starter-actuator"] spring-data = ["spring-boot-starter-data-jpa", "postgresql", "flyway-core"] gcp = ["spring-cloud-gcp-starter", "spring-cloud-gcp-pubsub", "google-cloud-secretmanager"] testing = ["junit-jupiter", "mockito-core", "spring-boot-starter-test"] testcontainers = ["testcontainers-junit", "testcontainers-postgresql"]

[plugins] spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" } spring-dependency-management = { id = "io.spring.dependency-management", version = "1.1.7" } jib = { id = "com.google.cloud.tools.jib", version = "3.4.4" }

undefined

junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" } mockito-core = { module = "org.mockito:mockito-core", version.ref = "mockito" } testcontainers-junit = { module = "org.testcontainers:junit-jupiter", version.ref = "testcontainers" } testcontainers-postgresql = { module = "org.testcontainers:postgresql", version.ref = "testcontainers" }

[bundles] spring-boot-web = ["spring-boot-starter-web", "spring-boot-starter-actuator"] spring-data = ["spring-boot-starter-data-jpa", "postgresql", "flyway-core"] gcp = ["spring-cloud-gcp-starter", "spring-cloud-gcp-pubsub", "google-cloud-secretmanager"] testing = ["junit-jupiter", "mockito-core", "spring-boot-starter-test"] testcontainers = ["testcontainers-junit", "testcontainers-postgresql"]

[plugins] spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" } spring-dependency-management = { id = "io.spring.dependency-management", version = "1.1.7" } jib = { id = "com.google.cloud.tools.jib", version = "3.4.4" }

undefined

Step 2: Configure in Settings File

步骤2：在设置文件中配置

Update

settings.gradle.kts

to use the version catalog:

kotlin

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
}

// For multi-module projects
rootProject.name = "supplier-charges"
include("shared-domain")
include("supplier-charges-hub")

更新

settings.gradle.kts

以使用版本目录：

kotlin

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
}

// 多模块项目配置
rootProject.name = "supplier-charges"
include("shared-domain")
include("supplier-charges-hub")

Step 3: Use in Build Scripts

步骤3：在构建脚本中使用

In

build.gradle.kts

, use type-safe dependency references:

kotlin

plugins {
    alias(libs.plugins.spring.boot)
    alias(libs.plugins.spring.dependency.management)
}

dependencies {
    // Single dependencies
    implementation(libs.spring.boot.starter.web)
    implementation(libs.mapstruct)
    annotationProcessor(libs.mapstruct.processor)

    // Bundles (groups of related dependencies)
    implementation(libs.bundles.spring.boot.web)
    implementation(libs.bundles.gcp)
    testImplementation(libs.bundles.testing)
    testImplementation(libs.bundles.testcontainers)
}

在

build.gradle.kts

中使用类型安全的依赖引用：

kotlin

plugins {
    alias(libs.plugins.spring.boot)
    alias(libs.plugins.spring.dependency.management)
}

dependencies {
    // 单个依赖
    implementation(libs.spring.boot.starter.web)
    implementation(libs.mapstruct)
    annotationProcessor(libs.mapstruct.processor)

    // 依赖包（相关依赖组）
    implementation(libs.bundles.spring.boot.web)
    implementation(libs.bundles.gcp)
    testImplementation(libs.bundles.testing)
    testImplementation(libs.bundles.testcontainers)
}

Step 4: Manage BOMs for Curated Versions

步骤4：使用BOM管理标准化版本

Use Bill of Materials to control transitive dependencies:

kotlin

// build.gradle.kts
dependencyManagement {
    imports {
        mavenBom("com.google.cloud:spring-cloud-gcp-dependencies:6.1.1")
        mavenBom("org.springframework.cloud:spring-cloud-dependencies:2024.0.1")
    }
}

dependencies {
    // No version needed - comes from BOM
    implementation("com.google.cloud:spring-cloud-gcp-starter")
    implementation("org.springframework.cloud:spring-cloud-config-client")
}

使用物料清单（BOM）来控制传递依赖：

kotlin

// build.gradle.kts
dependencyManagement {
    imports {
        mavenBom("com.google.cloud:spring-cloud-gcp-dependencies:6.1.1")
        mavenBom("org.springframework.cloud:spring-cloud-dependencies:2024.0.1")
    }
}

dependencies {
    // 无需指定版本 - 由BOM提供
    implementation("com.google.cloud:spring-cloud-gcp-starter")
    implementation("org.springframework.cloud:spring-cloud-config-client")
}

Step 5: Resolve Conflicts with Constraints

步骤5：通过约束解决冲突

Use dependency constraints to force specific versions without declaring the dependency:

kotlin

dependencies {
    // Actual dependencies
    implementation("org.springframework.boot:spring-boot-starter-web")

    // Constraints - enforce versions of transitive dependencies
    constraints {
        implementation("org.bouncycastle:bcprov-jdk15on:1.70")
        implementation("ch.qos.logback:logback-core:1.5.19")
    }
}

To exclude a problematic transitive dependency:

kotlin

dependencies {
    implementation("com.example:library:1.0") {
        exclude(group = "commons-logging", module = "commons-logging")
    }
}

使用依赖约束来强制特定版本，无需显式声明依赖：

kotlin

dependencies {
    // 实际依赖
    implementation("org.springframework.boot:spring-boot-starter-web")

    // 约束 - 强制传递依赖的版本
    constraints {
        implementation("org.bouncycastle:bcprov-jdk15on:1.70")
        implementation("ch.qos.logback:logback-core:1.5.19")
    }
}

排除有问题的传递依赖：

kotlin

dependencies {
    implementation("com.example:library:1.0") {
        exclude(group = "commons-logging", module = "commons-logging")
    }
}

Examples

示例

Example 1: Multi-Module with Shared Catalog

示例1：多模块项目与共享目录

toml

undefined

toml

undefined

gradle/libs.versions.toml

[versions] spring-boot = "3.5.5"

[libraries] spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web" } spring-boot-starter-test = { module = "org.springframework.boot:spring-boot-starter-test" }

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


```kotlin
// Root settings.gradle.kts
rootProject.name = "supplier-charges"

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
}

include("shared-domain")
include("supplier-charges-hub")
include("supplier-charges-worker")

kotlin

// shared-domain/build.gradle.kts
plugins {
    id("java-library")
}

dependencies {
    api(libs.spring.boot.starter.web)
}

kotlin

// supplier-charges-hub/build.gradle.kts
plugins {
    alias(libs.plugins.spring.boot)
}

dependencies {
    implementation(project(":shared-domain"))
    testImplementation(libs.spring.boot.starter.test)
}

[versions] spring-boot = "3.5.5"

[libraries] spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web" } spring-boot-starter-test = { module = "org.springframework.boot:spring-boot-starter-test" }

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


```kotlin
// 根目录settings.gradle.kts
rootProject.name = "supplier-charges"

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
}

include("shared-domain")
include("supplier-charges-hub")
include("supplier-charges-worker")

kotlin

// shared-domain/build.gradle.kts
plugins {
    id("java-library")
}

dependencies {
    api(libs.spring.boot.starter.web)
}

kotlin

// supplier-charges-hub/build.gradle.kts
plugins {
    alias(libs.plugins.spring.boot)
}

dependencies {
    implementation(project(":shared-domain"))
    testImplementation(libs.spring.boot.starter.test)
}

Example 2: Resolving Dependency Conflicts

示例2：解决依赖冲突

kotlin

// When Spring Boot and external library have conflicting versions
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("com.external:library:1.0")  // Uses old commons-lang3

    // Force the newer version
    constraints {
        implementation("org.apache.commons:commons-lang3:3.18.0")
    }
}

// Or use resolutionStrategy
configurations.all {
    resolutionStrategy {
        force("com.google.guava:guava:32.1.3-jre")
        force("org.apache.commons:commons-compress:1.26.0")
    }
}

kotlin

// 当Spring Boot与外部库版本冲突时
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("com.external:library:1.0")  // 使用旧版commons-lang3

    // 强制使用新版本
    constraints {
        implementation("org.apache.commons:commons-lang3:3.18.0")
    }
}

// 或使用resolutionStrategy
configurations.all {
    resolutionStrategy {
        force("com.google.guava:guava:32.1.3-jre")
        force("org.apache.commons:commons-compress:1.26.0")
    }
}

Example 3: Security-Focused Constraints

示例3：安全导向的约束

toml

undefined

toml

undefined

gradle/libs.versions.toml with security-critical versions

包含安全关键版本的gradle/libs.versions.toml

[constraints] bouncycastle = "1.70" # Cryptography logback = "1.5.19" # Logging jackson = "2.17.2" # JSON processing commons-lang3 = "3.18.0" # Common utilities


```kotlin
// build.gradle.kts
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")

    constraints {
        implementation("org.bouncycastle:bcprov-jdk15on:${libs.versions.bouncycastle.get()}")
        implementation("ch.qos.logback:logback-core:${libs.versions.logback.get()}")
        implementation("com.fasterxml.jackson.core:jackson-databind:${libs.versions.jackson.get()}")
        implementation("org.apache.commons:commons-lang3:${libs.versions.commons.lang3.get()}")
    }
}

[constraints] bouncycastle = "1.70" # 加密库 logback = "1.5.19" # 日志库 jackson = "2.17.2" # JSON处理库 commons-lang3 = "3.18.0" # 通用工具库


```kotlin
// build.gradle.kts
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")

    constraints {
        implementation("org.bouncycastle:bcprov-jdk15on:${libs.versions.bouncycastle.get()}")
        implementation("ch.qos.logback:logback-core:${libs.versions.logback.get()}")
        implementation("com.fasterxml.jackson.core:jackson-databind:${libs.versions.jackson.get()}")
        implementation("org.apache.commons:commons-lang3:${libs.versions.commons.lang3.get()}")
    }
}

Example 4: Using Version Ref in BOM

示例4：在BOM中使用版本引用

toml

undefined

toml

undefined

gradle/libs.versions.toml

[versions] spring-cloud-gcp = "6.1.1"

[libraries] spring-cloud-gcp-bom = { module = "com.google.cloud:spring-cloud-gcp-dependencies", version.ref = "spring-cloud-gcp" } spring-cloud-gcp-starter = { module = "com.google.cloud:spring-cloud-gcp-starter" } spring-cloud-gcp-pubsub = { module = "com.google.cloud:spring-cloud-gcp-starter-pubsub" }

[bundles] gcp = ["spring-cloud-gcp-starter", "spring-cloud-gcp-pubsub"]


```kotlin
// build.gradle.kts
dependencyManagement {
    imports {
        mavenBom(libs.spring.cloud.gcp.bom.get().toString())
    }
}

dependencies {
    implementation(libs.bundles.gcp)
}

[versions] spring-cloud-gcp = "6.1.1"

[libraries] spring-cloud-gcp-bom = { module = "com.google.cloud:spring-cloud-gcp-dependencies", version.ref = "spring-cloud-gcp" } spring-cloud-gcp-starter = { module = "com.google.cloud:spring-cloud-gcp-starter" } spring-cloud-gcp-pubsub = { module = "com.google.cloud:spring-cloud-gcp-starter-pubsub" }

[bundles] gcp = ["spring-cloud-gcp-starter", "spring-cloud-gcp-pubsub"]


```kotlin
// build.gradle.kts
dependencyManagement {
    imports {
        mavenBom(libs.spring.cloud.gcp.bom.get().toString())
    }
}

dependencies {
    implementation(libs.bundles.gcp)
}

Requirements

要求

Gradle 7.0+ (version catalogs stable since Gradle 7.0)
```
settings.gradle.kts
```
file in project root
Spring Boot Gradle plugin for Spring Boot projects (optional but recommended)

Gradle 7.0+（版本目录在Gradle 7.0后稳定）
项目根目录存在
```
settings.gradle.kts
```
文件
Spring Boot项目可使用Spring Boot Gradle插件（可选但推荐）

Commands

命令

bash

undefined

bash

undefined

List all dependencies

列出所有依赖

./gradlew dependencies

Show dependency tree for specific configuration

查看特定配置的依赖树

./gradlew dependencies --configuration implementation

Show why a dependency is included

查看某个依赖被引入的原因

./gradlew dependencyInsight --dependency spring-core

Refresh dependencies (force re-download)

刷新依赖（强制重新下载）

./gradlew build --refresh-dependencies

Lock dependency versions for reproducibility

锁定依赖版本以实现可复现构建

./gradlew dependencies --write-locks

Verify against lock files

验证依赖是否符合锁定文件

./gradlew dependencies --verify-locks

Generate HTML dependency report

生成HTML格式的依赖报告

./gradlew htmlDependencyReport

undefined

./gradlew htmlDependencyReport

undefined

gradle-dependency-management

Original

Translation

Gradle Dependency Management

Gradle依赖管理

Table of Contents

目录

Purpose

用途

When to Use

适用场景

Quick Start

快速开始

Instructions

操作步骤

Step 1: Set Up Version Catalog

步骤1：设置版本目录

Spring Boot

Spring Boot

GCP

GCP

Database

数据库

MapStruct

MapStruct

Testing

测试

Step 2: Configure in Settings File

步骤2：在设置文件中配置

Step 3: Use in Build Scripts

步骤3：在构建脚本中使用

Step 4: Manage BOMs for Curated Versions

步骤4：使用BOM管理标准化版本

Step 5: Resolve Conflicts with Constraints

步骤5：通过约束解决冲突

Examples

示例

Example 1: Multi-Module with Shared Catalog

示例1：多模块项目与共享目录

gradle/libs.versions.toml

gradle/libs.versions.toml

Example 2: Resolving Dependency Conflicts

示例2：解决依赖冲突

Example 3: Security-Focused Constraints

示例3：安全导向的约束

gradle/libs.versions.toml with security-critical versions

包含安全关键版本的gradle/libs.versions.toml

Example 4: Using Version Ref in BOM

示例4：在BOM中使用版本引用

gradle/libs.versions.toml

gradle/libs.versions.toml

Requirements

要求

Commands

命令

List all dependencies

列出所有依赖

Show dependency tree for specific configuration

查看特定配置的依赖树

Show why a dependency is included

查看某个依赖被引入的原因

Refresh dependencies (force re-download)

刷新依赖（强制重新下载）

Lock dependency versions for reproducibility

锁定依赖版本以实现可复现构建

Verify against lock files

验证依赖是否符合锁定文件

Generate HTML dependency report

生成HTML格式的依赖报告

See Also

相关链接