1. 依赖传递基础

依赖传递（Transitive Dependency）是现代构建系统的核心机制之一。当项目声明一个直接依赖时，该依赖自身的依赖（即间接依赖）会自动被解析并加入项目编译或运行时路径。Gradle 默认启用传递依赖，但开发者需要通过一系列配置精确控制传递范围，避免版本冲突、冗余依赖和构建膨胀。

1.1 传递依赖概念

传递依赖形成一个多层依赖树。例如项目 A 依赖库 B，而 B 依赖 C，则 C 自动成为 A 的传递依赖。

1.2 Gradle 默认行为

Gradle 的默认依赖配置（如 implementation、api、compileOnly）决定了传递依赖的暴露范围。下表列出常用配置的传递性差异：

默认情况下，Gradle 会为所有声明的依赖（除 compileOnly 和 runtimeOnly 外）引入传递依赖。

1.3 传递性标志配置

开发者可以通过 transitive 属性全局禁用或按依赖粒度控制传递解析。配置方式如下：

// 在 build.gradle 中全局关闭传递依赖
configurations.all {
    transitive = false
}

// 或为单个依赖关闭传递
dependencies {
    implementation('com.example:lib:1.0') {
        transitive = false
    }
}

此外，Gradle 提供更精细的控制工具：

• exclude：排除特定传递依赖。
• force：强制指定某个依赖的版本，覆盖传递引入的版本。
• strictly：声明严格的版本约束，传递解析必须满足。

1.4 依赖传递解析流程

下图展示了一个典型依赖传递解析路径，并标注了控制点：

1.5 调试依赖传递

使用 Gradle 提供的依赖分析命令查看完整依赖树，定位传递来源：

# 查看所有依赖树（包含传递依赖）
gradle dependencies --configuration compileClasspath

# 查看特定模块的依赖树
gradle :app:dependencies

# 输出到文件便于分析
gradle dependencies > deps.txt

输出示例中，传递依赖会以 \--- 或 +\--- 缩进显示，并标注版本和冲突信息。

1.6 常见错误与避坑

• 版本冲突：多个传递依赖引入同一库的不同版本，Gradle 默认选择最高版本，可能导致不兼容。使用 force 或 strictly 统一版本。
• 遗漏必要传递依赖：全局关闭 transitive = false 后，需要手动补全所有缺失的依赖。
• 过度暴露 api 依赖：误用 api 导致消费者被迫传递依赖，增大构建范围。应优先使用 implementation。