📚 课程目录第4章依赖管理优化

依赖管理优化：声明依赖最佳实践

依赖声明这件事，听起来简单对吧？不就是把库的坐标加进来嘛。可我在优化过的项目里见过太多「优雅」的构建配置，最终被依赖管理搞得一团糟。你想想看，如果写错了声明策略，构建时间不会变慢，但渲染耗时、缓存失效、模块间耦合——全都找上门了。

我个人习惯把依赖声明看作是构建性能的「第一道防线」。写得不好，后面折腾再多的并行、缓存都是事倍功半。这章节我们就来聊聊，如何从源头把依赖声明这块做到极致。

依赖声明的核心问题

我先问问你，你写依赖声明时最关心什么？版本号？库名？其实真正影响构建性能的，是依赖声明的精确度和作用域。我见过不少项目，Gradle 文件里全是动态版本号，或者明明只在编译时用到的库，非要声明成 api 对整个模块透传——这些看似无害的习惯，恰恰是渲染耗时上升的元凶。

我在处理一个电商项目时，发现它的依赖解析耗时占整个构建的 16%。仔细排查后发现，很多 jar 包版本用的是 + 号，Gradle 每次都要联网查询最新版本，缓存几乎形同虚设。之后改成固定版本，解析时间直接降到现在一半以下。

动态版本与锁定文件

说句大白话：动态版本就是构建性能的定时炸弹。什么 1.0.+、[2.0,) 这种写法，虽然方便，但每次构建都要做网络查询，缓存全部失效。大多数情况下，真正的项目不需要每天升级依赖。

声明方式	示例	缓存命中	性能影响
固定版本	com.google.guava:guava:30.1-jre	✅ 稳定命中	优
动态版本	com.google.guava:guava:30.+	❌ 频繁失效	差
范围版本	com.google.guava:guava:[29.0,31.0)	❌ 网络查询	非常差

我建议你使用依赖锁定文件（gradle.lockfile）配合固定版本。这样构建时完全跳过版本解析逻辑，直接读取缓存。你的 CI 环境会感谢这个决定。

毒瘤配置全废弃

你还在用 compile 和 runtime 吗？我建议立刻停掉。从 Gradle 3.4 开始，api 和 implementation 已经替代了旧配置，原因很直接：限制依赖的传递性。

api：暴露给模块的消费者，会触发级联编译。
implementation：只对当前模块可见，不会透传给下游。

核心原则：能用 implementation 就绝不用 api。这是控制模块重编译范围的关键手段。

举个例子，你一个底层工具模块，引用了 okhttp 做网络请求。如果用 api，所有依赖这个工具模块的业务模块都会收到 okhttp 的变化通知，一旦 okhttp 版本升级，整个依赖链条都要重编译。而用 implementation，变化只影响工具模块自己。

// ❌ 不推荐
api 'com.squareup.okhttp3:okhttp:4.9.0'

// ✅ 推荐
implementation 'com.squareup.okhttp3:okhttp:4.9.0'

传递依赖的隐性消耗

有时候你只引入一个库，它却给你带来十几个 transitive 依赖。这些依赖不仅增加了类路径的体积，还可能卷入版本冲突，ausing 二次解析。我在一个金融项目中遇到过这种情况，一个 http 库拉来了三个版本的日志框架，导致构建时反复解析，每次都要多花 2 秒。

解决方式很简单：对不需要的传递依赖做排除。

implementation('com.example:some-library:1.0.0') {
    exclude group: 'commons-logging', module: 'commons-logging'
}

小技巧：运行 gradle dependencies --configuration compileClasspath，可以清楚看到每个依赖的来源和传递关系。我用这个命令排查过无数次依赖冲突。

还有一种情况是，你强制统一版本，避免 Gradle 做自动版本升级。

configurations.all {
    resolutionStrategy {
        force 'com.fasterxml.jackson.core:jackson-databind:2.12.3'
        preferProjectModules()
        failOnVersionConflict()
    }
}

版本目录（Version Catalog）

Gradle 7.0 开始正式支持版本目录。它最大的价值不是代码整洁，而是统一版本声明，减少解析冲突。

我在一个多模块项目中把所有依赖版本收拢到 libs.versions.toml 里，子模块只管引用 catalog 条目。结果怎么样？之前时不时出现的「版本混乱导致全量重编译」消失了，模块的并行增量构建成功率提升了近 20%。

// libs.versions.toml
[versions]
kotlin = "1.5.21"
okhttp = "4.9.0"

[libraries]
okhttp-core = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }
kotlin-stdlib = { group = "org.jetbrains.kotlin", name = "kotlin-stdlib", version.ref = "kotlin" }

常见坑：我曾经直接在一个模块里混用了 catalog 和直接声明版本号。Gradle 不会自动帮你合并策略，最后解析器选错了版本，导致运行时炸了。所以，要么全用 catalog，要么不用，不要混搭。

依赖约束（Dependency Constraints）

如果你的项目是多模块架构，不同模块引入了同一个库的不同版本，Gradle 默认会选最高版本。可有时候最高版本并不兼容。这时候依赖约束就有用了。

我不建议在子模块里手工标记版本一致性，那太容易出错。不如在根项目的 subprojects 里统一声明 constraint。

dependencies {
    constraints {
        implementation 'com.google.guava:guava:30.1-jre'
        implementation 'org.slf4j:slf4j-api:1.7.30'
    }
}

这样做的好处是：所有模块在解析时都会被约束到指定版本，不需要每个 build.gradle 里重复写。减少了重复声明，也降低了版本冲突的概率。说白了，就是用约束替死的版本号，保证一致性。

依赖声明检查清单

我把依赖声明的关键检查点整理成了一张表，每当你添加一个新依赖，建议过一遍这个 list：

检查项	操作	对性能的影响
是否用了动态版本？	改为固定版本	缓存命中提升，解析耗时减少
是否用了 compile 或 runtime？	改为 implementation	模块重编译范围大幅缩减
是否存在不需要的传递依赖？	显式 exclude	类路径体积变小，解析更稳定
版本是否统一管理？	使用 version catalog	版本一致性保障，减少冲突
是否通过 constraint 做了版本约束？	在根项目里声明	全局统一，避免局部混乱

核心一句话：依赖声明的最佳实践，本质上是让你从「能用就行」变成「精准可控」。每一次精确的声明，都在为你的构建性能争取时间。

说实话，依赖声明优化是所有构建优化中最容易落地的一步。它不需要你改代码逻辑，不用动模块设计，只要把这些声明规则坚持下去，你的 Gradle 构建就能稳定不少。我带的几个团队，实施这些策略后，基线构建时间普遍降低了 10-15%。