1. 版本目录 (Version Catalogs)

版本目录是 Gradle 7.0 引入的一项功能，它提供了一种集中管理依赖版本和依赖组的强大方式，尤其适合多模块项目。

1. 版本目录的概念与优势

版本目录是一种将依赖定义从构建脚本中抽离出来的机制，使依赖管理更加结构化、集中化，并支持更好的 IDE 支持。

2. 主要优势

1. 集中管理：在一个地方定义所有依赖版本和依赖组
2. 类型安全：提供类型安全的依赖访问，减少拼写错误
3. IDE 支持：更好的自动完成和导航支持
4. 依赖分组：按逻辑组织依赖
5. 版本控制：轻松更新和跟踪依赖版本变化

3. 基本配置

版本目录通常在 settings.gradle 或 settings.gradle.kts 文件中定义：

// 在settings.gradle中
dependencyResolutionManagement {versionCatalogs {libs {// 定义版本version('kotlin', '1.6.10')version('coroutines', '1.6.0')// 定义库library('kotlin-stdlib', 'org.jetbrains.kotlin', 'kotlin-stdlib').versionRef('kotlin')library('kotlin-reflect', 'org.jetbrains.kotlin', 'kotlin-reflect').versionRef('kotlin')library('coroutines-core', 'org.jetbrains.kotlinx', 'kotlinx-coroutines-core').versionRef('coroutines')// 定义依赖组（bundle）bundle('kotlin-bundle', ['kotlin-stdlib', 'kotlin-reflect'])// 定义插件plugin('kotlin-android', 'org.jetbrains.kotlin.android').versionRef('kotlin')}}
}

在 Kotlin DSL 中（settings.gradle.kts）：

dependencyResolutionManagement {versionCatalogs {create("libs") {version("kotlin", "1.6.10")version("coroutines", "1.6.0")library("kotlin-stdlib", "org.jetbrains.kotlin", "kotlin-stdlib").versionRef("kotlin")library("kotlin-reflect", "org.jetbrains.kotlin", "kotlin-reflect").versionRef("kotlin")library("coroutines-core", "org.jetbrains.kotlinx", "kotlinx-coroutines-core").versionRef("coroutines")bundle("kotlin-bundle", listOf("kotlin-stdlib", "kotlin-reflect"))plugin("kotlin-android", "org.jetbrains.kotlin.android").versionRef("kotlin")}}
}

4. 使用版本目录

一旦定义了版本目录，我们就可以在构建脚本中使用它们：

plugins {id(libs.plugins.kotlin.android.get().pluginId)
}dependencies {implementation(libs.kotlin.stdlib)implementation(libs.coroutines.core)implementation(libs.bundles.kotlin.bundle)
}

5.使用外部版本目录文件

对于更复杂的项目，您可以将版本目录定义移动到专用的 TOML 文件中, 当然这也是Android官方推荐的做法，在新的AS项目中，默认就是使用的 TOML文件：

# libs.versions.toml
[versions]
kotlin = "1.6.10"
coroutines = "1.6.0"
retrofit = "2.9.0"
okhttp = "4.9.3"
room = "2.4.1"[libraries]
kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }
kotlin-reflect = { module = "org.jetbrains.kotlin:kotlin-reflect", version.ref = "kotlin" }
coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
coroutines-android = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-android", version.ref = "coroutines" }
retrofit-core = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
retrofit-gson = { module = "com.squareup.retrofit2:converter-gson", version.ref = "retrofit" }
okhttp-core = { module = "com.squareup.okhttp3:okhttp", version.ref = "okhttp" }
okhttp-logging = { module = "com.squareup.okhttp3:logging-interceptor", version.ref = "okhttp" }
room-runtime = { module = "androidx.room:room-runtime", version.ref = "room" }
room-compiler = { module = "androidx.room:room-compiler", version.ref = "room" }[bundles]
kotlin = ["kotlin-stdlib", "kotlin-reflect"]
coroutines = ["coroutines-core", "coroutines-android"]
retrofit = ["retrofit-core", "retrofit-gson", "okhttp-core", "okhttp-logging"]
room = ["room-runtime"][plugins]
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
kotlin-kapt = { id = "org.jetbrains.kotlin.kapt", version.ref = "kotlin" }

然后在 settings.gradle 中引用这个文件:

dependencyResolutionManagement {versionCatalogs {libs {from(files("libs.versions.toml"))}}
}

6.实际项目中的版本目录最佳实践

1. 按功能或技术栈分组：将依赖按照功能或技术栈分组，例如 network、ui、database 等。
2. 使用有意义的别名：为依赖创建直观的别名，如 retrofit 而不是 squareup-retrofit。
3. 充分利用版本引用：避免重复的版本号声明，使用版本引用确保相关库使用相同版本。
4. 创建有用的 bundle：将常一起使用的依赖组合成 bundle，简化依赖声明。
5. 保持 TOML 文件的良好组织：使用注释和分组保持文件可读性。

例如以下：

# 网络相关依赖
[libraries.retrofit]
module = "com.squareup.retrofit2:retrofit"
version = "2.9.0"# 注释说明特殊用途的依赖
[libraries.leak-canary]
module = "com.squareup.leakcanary:leakcanary-android"
version = "2.8.1"
# 仅在 debug 构建中使用

2. 依赖锁定（Dependency Locking）

依赖锁定是确保构建可重复性的重要技术，特别是当项目使用动态版本或版本范围时。

1. 依赖锁定的概念与重要性

依赖锁定将依赖图"冻结"在特定的时间点，记录解析的确切版本，确保后续构建使用相同的依赖版本，即使新版本发布。

2. 主要优势

1. 构建可重现性：确保相同的源代码总是使用相同的依赖版本构建
2. 防止意外升级：避免自动获取新发布的库版本
3. 行为一致性：减少"在我的机器上能运行"问题
4. 安全性：在审核新版本之前防止引入新依赖

3. 如何启用依赖锁定

在 settings.gradle 或特定项目的 build.gradle 中启用依赖锁定：

// 为所有配置启用依赖锁定
dependencyLocking {lockAllConfigurations()
}// 或者为特定配置启用
configurations.compileClasspath {resolutionStrategy.activateDependencyLocking()
}

4. 生成锁定文件

一旦启用了依赖锁定，您需要生成锁定文件：

# 为所有配置生成锁定文件
./gradlew dependencies --write-locks# 为特定项目生成锁定文件
./gradlew :app:dependencies --write-locks

这将在 gradle/dependency-locks 目录下创建锁定文件，每个配置一个文件。

5. 更新锁定依赖

当需要有意更新依赖版本时:

# 更新所有依赖锁
./gradlew dependencies --update-locks "com.squareup.retrofit2:*"# 或者完全刷新所有锁
./gradlew dependencies --write-locks

6. 依赖锁定与版本目录结合使用

依赖锁定和版本目录可以很好地结合使用,这种组合确保您既有集中的版本管理，又有确切的依赖锁定，提供最大的可重复性和控制。

• 版本目录：声明您期望的依赖版本（理想状态）
• 依赖锁定：记录实际解析的版本（实际状态）

// 在build.gradle中
dependencies {implementation libs.retrofit.core // 从版本目录
}dependencyLocking {lockAllConfigurations()
}

这里可能稍微难理解，我用个例子简单来描述一下。

假设我们开发的App中， Retrofit 2.9.0 依赖 OkHttp 4.9.0，但我们在版本目录中指定了更新的 OkHttp 4.9.3，

当没有依赖锁定时：

• 第一个开发者构建项目时会使用 OkHttp 4.9.3
• 下一个开发者几周后构建项目，可能 OkHttp 已更新到 4.9.5，他将使用 4.9.5

开启依赖锁定后：

• 所有开发者都会使用锁定文件中的精确版本 OkHttp 4.9.3
• 即使 OkHttp 发布了 4.9.5 版本，除非我们显式更新锁定文件，否则团队仍会使用 4.9.3

现在假设我们的目录版本中更新了Gson：

[versions]
# 更新了版本
gson = "2.9.0" # 从 2.8.5 更新

有了依赖锁定：

1. 即使版本目录更新了，项目仍会使用锁定文件中的 2.8.5
2. 团队可以讨论并决定何时更新锁定文件
3. 当团队准备好时，可以显式更新锁定：

./gradlew dependencies --update-locks "com.google.gson*:*"

3. 依赖缓存与离线构建

有效管理依赖缓存可以显著提高构建性能，特别是在团队环境或 CI/CD 管道中。

1. Gradle 的依赖缓存机制

Gradle 在本地缓存所有下载的依赖，默认位置是用户主目录下的 .gradle/caches 目录。

2. 配置缓存位置

我们可以自定义缓存位置, 在 gradle.properties中：

# gradle.properties
org.gradle.caching=true
org.gradle.caching.debug=false
org.gradle.cache.dir=/custom/cache/directory

3. 启用构建缓存

构建缓存可以在配置中启用：

# settings.gradle
buildCache {local {enabled = true}
}

4. 离线模式构建

离线模式强制 Gradle 只使用缓存的依赖:

# 命令行参数
./gradlew build --offline# 或在 gradle.properties 中永久设置
org.gradle.offline=true

5. 依赖缓存的最佳实践

1. 共享缓存：考虑在团队之间或 CI 系统中共享缓存目录，减少重复下载

2. 定期清理：定期清理缓存，删除不再使用的依赖版本

./gradlew cleanBuildCache

3. 预热缓存：在 CI 构建前或开发环境设置中预热缓存

./gradlew downloadDependencies

4. 缓存备份：备份关键依赖的缓存，防止远程仓库不可用

5. 使用镜像或私有仓库：设置本地镜像或私有依赖仓库，减少外部依赖.