在大型 Android 项目中，有些依赖库往往是“全家桶”出现的。比如：

  • 网络请求：Retrofit + OkHttp + GSON 转换器 + 日志拦截器。

  • Jetpack Compose：Compose UI + Material 3 + Tooling + Activity Compose。

  • 单元测试：JUnit + Mockito + Truth。

在以前，如果你有 10 个子模块都要用 Compose，你得在 10 个 build.gradle 里重复写 5 到 6 行 implementation。现在，通过 bundles，我们可以实现**“一行代码，全家桶到家”**。

一、 什么是 [bundles]？

如果说 libraries 是超市里的单品（汉堡、可乐、薯条），那么 bundles 就是超市里的超值套餐。

你只需要在 TOML 里定义一次套餐内容，在模块里直接点“套餐编号”即可。

二、 实战演示：从“满屏依赖”到“一行搞定”

1. 在 libs.versions.toml 中定义

我们以“网络库全家桶”为例。

Ini, TOML

[versions]
retrofit = "2.9.0"
okhttp = "4.11.0"

[libraries]
# 先定义单品
retrofit-core = { group = "com.squareup.retrofit2", name = "retrofit", version.ref = "retrofit" }
retrofit-gson = { group = "com.squareup.retrofit2", name = "converter-gson", version.ref = "retrofit" }
okhttp-core = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }
okhttp-logging = { group = "com.squareup.okhttp3", name = "logging-interceptor", version.ref = "okhttp" }

[bundles]
# 定义套餐：把上面的单品别名组合在一起
networking = [
    "retrofit-core",
    "retrofit-gson",
    "okhttp-core",
    "okhttp-logging"
]

2. 在子模块 build.gradle 中引用

【改造前】：

Gradle

dependencies {
    implementation(libs.retrofit.core)
    implementation(libs.retrofit.gson)
    implementation(libs.okhttp.core)
    implementation(libs.okhttp.logging)
}

【改造后】：

Gradle

dependencies {
    // 只要这一行，上面的 4 个库全部自动引入
    implementation(libs.bundles.networking)
}

三、 为什么 bundles 这么好用？

1. 强迫症的福音

子模块的 dependencies 块将从几十行缩减到几行。你的配置文件变得非常有语义化：implementation(libs.bundles.compose.ui) 一眼就能看出这个模块支持了 UI 功能，而不是被一堆具体的坐标淹没。

2. 维护成本降为零

如果某天你需要更换网络日志库，或者想给所有模块统一增加一个 Retrofit 的插件，你只需要改 TOML 文件里的 [bundles] 列表。 全项目所有引用了该 bundle 的子模块会自动同步，不需要你挨个文件去翻找。

3. 避免“漏掉依赖”

新手在配置 Compose 时经常漏掉 compose-ui-tooling-preview 导致预览失败。通过 bundle，资深开发者可以把“Compose 必备清单”配好，新手直接引用 bundle 即可，确保环境完全一致。

四、 总结：Gradle 现代化的“最终拼图”

回顾我们这一系列的讨论，一个完美的现代 Gradle 项目结构应该是这样的：

  1. libs.versions.toml：唯一的真相来源。存储版本、定义单品、打包套餐。

  2. 根目录 build.gradle：规矩的制定者。利用 alias 和 apply false 锁定插件版本。

  3. 子模块 build.gradle：纯粹的执行者。利用 alias 开启功能，利用 libs.bundles 一键装载依赖。