4. 依赖传递机制：传递依赖自动解析、依赖树查看、transitive属性控制

4.1 原理：传递依赖自动解析

当你在 build.gradle 中声明一个直接依赖（例如 Spring Boot），Gradle 不仅会拉取该组件本身，还会将该组件自身的依赖关系——传递依赖——一并解析并纳入你的类路径。Gradle 的解析引擎遵循以下核心策略：

• 最近优先原则：在依赖树中，距离根项目最近（层级最深）的版本被选中。
• 第一声明优先：当两个直接依赖需要同一个传递依赖的不同版本时，先声明的依赖版本获胜。
• 强制版本：使用 strictly 或 force 可覆盖所有传递版本。

4.2 依赖树查看：gradle dependencies 命令

查看当前项目的完整依赖树，识别传递来源与版本冲突：

# 列出所有配置的依赖树
gradle dependencies

# 仅查看 compileClasspath（Java 库）
gradle dependencies --configuration compileClasspath

# 以 HTML 格式输出至文件
gradle dependencies --info > deps.txt

输出示例（简化）：

compileClasspath - Compile classpath for source set 'main'.
\--- com.example:lib-a:1.0
     \--- com.example:lib-b:2.1
          \--- com.example:lib-c:3.0 -> 3.1 (version forced)

-> 表示版本已通过冲突解决被升级或降级。

4.3 transitive 属性：控制依赖传递粒度

transitive 属性用于关闭或开启某条依赖的传递性，避免引入不需要的间接依赖。

在 build.gradle 中声明：

dependencies {
    implementation('com.example:lib-a:1.0') {
        transitive = false   // 关闭 lib-a 的所有传递依赖
    }

    implementation('com.example:lib-b:2.0') {
        exclude group: 'com.unwanted', module: 'ugly-lib'  // 仅排除某个传递依赖
    }
}

4.4 传递依赖解析流程

Gradle 在执行 dependencies 任务时，从根项目出发，递归遍历每个依赖的 gradle module metadata（或 POM），构建依赖图，然后按照冲突策略裁决版本，最后将结果写入缓存。完整流程如下图所示：

4.5 常见错误与调试

• NoSuchMethodError / ClassNotFoundException：传递依赖版本被错误升级或降级，导致运行时二进制不兼容。使用 gradle dependencies --configuration runtimeClasspath 检查冲突。
• Unexpected transitive dependency：某个库引入了大量无用库（如 Log4j → Log4j 老版本），可通过 transitive = false 或 exclude 剔除。
• 版本锁定失效：如果同时使用 strictly 和 transitive=false，优先级取决于执行顺序。建议在 constraints 块中统一声明。

4.6 性能与稳定性优化

• 关闭不必要的传递依赖：对已知无子依赖的独立工具库（如 JUnit），保持默认；对大型企业库（如 Spring Boot），如果业务仅需少量模块，使用 transitive = false 并手动添加所需传递。
• 使用依赖约束集中管理：在 dependencyConstraints 中定义传递依赖的版本，避免在每个子模块重复 exclude。
• 缓存预热：CI 构建前执行 gradle dependencies --offline 将依赖树写入缓存，减少解析耗时。
• 启用并行解析：在 gradle.properties 中设置 org.gradle.parallel=true，可加速多模块项目的依赖图构建。