📚 课程目录第1章依赖传递核心机制

第1章依赖传递核心机制

依赖传递是 Gradle 构建体系中控制第三方库“传染”范围的核心规则。理解它的三个支柱——传递性声明、版本冲突仲裁以及编译/运行时作用域——是消除构建不稳定、运行时 NoClassDefFoundError 和构建时间膨胀的基础。

1.1 传递性声明

Gradle 中依赖默认具有传递性（transitive = true）。当项目声明依赖 A 时，A 的所有依赖（B、C）也会被自动引入。关闭传递性可阻止依赖“传染”，常用于隔离特定库的子依赖。

性能建议：对于已知不需要的传递性依赖，使用 transitive = false 可减少解析时间和构建缓存大小，尤其适用于大型 monorepo。

配置示例（build.gradle）：

dependencies {
    // 默认传递性
    implementation 'com.example:lib-a:1.0'

    // 关闭传递性
    implementation('com.example:lib-b:2.0') {
        transitive = false
    }

    // 更细粒度：排除特定模块
    implementation('com.example:lib-c:3.0') {
        exclude module: 'unwanted-module'
        exclude group: 'com.old-dep'
    }
}

模式	行为	典型使用场景
`transitive = true`（默认）	引入所有传递性依赖	大多数框架集成（Spring Boot、JUnit）
`transitive = false`	仅引入直接声明的依赖	隔离日志实现、消除冗余依赖
`exclude`	排除指定 group/module 的传递性依赖	消除版本冲突、替换为更高版本

1.2 版本冲突仲裁

当多个依赖传递引入同一库的不同版本时，Gradle 的默认策略是选择最新版本（"newest"）。也可以通过 failOnVersionConflict() 或强制版本覆盖默认行为。

常见错误：默认“选择最新”策略可能导致非预期的 API 变更。务必使用 dependencyInsight 任务验证最终选择的版本：

gradle dependencyInsight --dependency logback-classic --configuration runtimeClasspath

输出会显示所有候选版本、冲突原因及最终仲裁结果。

强制版本与严格版本约束：

dependencies {
    // 强制版本（覆盖所有传递性依赖中的版本）
    implementation('com.example:lib-core:2.5') {
        force = true
    }

    // 严格版本（要求必须使用指定版本，否则构建失败）
    implementation('com.example:lib-core:2.5!!')  // 等价于strictly

    // 版本约束（声明平台版本对齐）
    constraints {
        implementation('com.example:lib-core:2.5') {
            because '安全修复需要2.5及以上版本'
        }
    }
}

策略	Gradle 方式	效果
最新版本（默认）	无特殊声明	自动选择最高的版本
严格失败	`failOnVersionConflict()`	版本不一致时构建失败（严格模式）
强制版本	`force = true`	覆盖所有传递性引入的同组件版本
严格版本	`1.0!!` 或 `strictly '1.0'`	要求精确匹配，否则解析失败
版本约束	`constraints` 块	声明平台级版本约定，具可解释性

1.3 编译/运行时作用域

作用域决定了依赖在构建阶段和运行时的可见性。Gradle 的 api、implementation、compileOnly、runtimeOnly 配置不仅控制类路径，还影响传递性暴露范围。

作用域对比表：

配置	编译期暴露	运行时暴露	传递性	使用场景
`api`	是	是	透传给消费者	库的公共 API 依赖（如 Spring Boot Starter）
`implementation`	否（仅当前模块）	是	不透传	内部实现细节（推荐优先使用）
`compileOnly`	是	否	不透传	编译期注解处理器、Servlet API
`runtimeOnly`	否	是	不透传	JDBC 驱动、日志实现

关键原则：使用 implementation 而非 api 可大幅缩短编译类路径，减少重新编译的范围（Gradle 将自动跳过未变更的内部依赖的重新编译）。这是优化增量构建性能的核心手段。

作用域与传递性的综合示例：

dependencies {
    // 公共 API 依赖 -> 透传给消费者
    api 'org.springframework.boot:spring-boot-starter-web:3.2.0'

    // 内部实现 -> 不透传
    implementation 'com.fasterxml.jackson.core:jackson-databind:2.16.0'
    implementation 'org.slf4j:slf4j-api:2.0.9'

    // 仅编译期需要 -> 不透传
    compileOnly 'org.projectlombok:lombok:1.18.30'

    // 仅运行时需要 -> 不透传
    runtimeOnly 'org.postgresql:postgresql:42.7.0'
}

📚 课程目录

第1章 依赖传递核心机制

1.1 传递性声明

1.2 版本冲突仲裁

1.3 编译/运行时作用域

第1章依赖传递核心机制