gradle-dependency-management（Gradle 依赖管理）

Gradle Dependency Management

Table of Contents

• Purpose
• When to Use
• Quick Start
• Instructions
• Examples
• Requirements
• Commands
• See Also

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.

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

Quick Start

Create a version catalog in gradle/libs.versions.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:

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

Use in build.gradle.kts:

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

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

Instructions

Step 1: Set Up Version Catalog

Create gradle/libs.versions.toml with your project's dependencies:

[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" }

Step 2: Configure in Settings File

Update settings.gradle.kts to use the version catalog:

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")

Step 3: Use in Build Scripts

In build.gradle.kts, use type-safe dependency references:

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)
}

Step 4: Manage BOMs for Curated Versions

Use Bill of Materials to control transitive dependencies:

// 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")
}

Step 5: Resolve Conflicts with Constraints

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

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:

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

Examples

Example 1: Multi-Module with Shared Catalog

# 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" }

// 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")

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

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

// 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

// 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")
    }
}

Example 3: Security-Focused Constraints

# gradle/libs.versions.toml with security-critical versions
[constraints]
bouncycastle = "1.70"           # Cryptography
logback = "1.5.19"              # Logging
jackson = "2.17.2"              # JSON processing
commons-lang3 = "3.18.0"        # Common utilities

// 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

# 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"]

// 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)

Commands

# 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
./gradlew htmlDependencyReport

See Also

• Gradle Version Catalogs Documentation
• Spring Boot BOM Integration
• gradle-performance-optimization - Enable build cache for faster dependency resolution
• gradle-troubleshooting - Resolve dependency conflict issues