11.1.4 Gradle 最佳实践

原文链接: https://kotlinlang.org/docs/gradle-best-practices.html

11.1.4 Gradle 最佳实践

Gradle 是许多 Kotlin 项目用来自动化和管理构建过程的构建系统。

充分利用 Gradle 非常关键，它能帮你减少管理和等待构建的时间，把更多时间用于编码。这里我们提供一组最佳实践，分为两个关键方面：组织和优化你的项目。

组织

本节重点介绍如何组织 Gradle 项目结构，以提高清晰度、可维护性和可扩展性。

使用 Kotlin DSL

使用 Kotlin DSL 而不是传统的 Groovy DSL。这样你就不必再学习另一门语言，同时还能获得严格类型检查的好处。严格类型让 IDE 能更好地支持重构和自动补全，从而提高开发效率。

更多信息请参阅 Gradle 的 Kotlin DSL 入门。

阅读 Gradle 关于 Kotlin DSL 成为 Gradle 构建默认选择的那篇博客。

使用版本目录

使用 libs.versions.toml 文件中的版本目录来集中管理依赖。这样你就可以在各项目之间一致地定义和复用版本、库和插件。

1
2
3
4
5

[versions]
kotlinxCoroutines = "1.11.0"

[libraries]
kotlinxCoroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlinxCoroutines" }

并在你的 build.gradle.kts 文件中加入以下依赖：

1
2
3

dependencies {
    implementation(libs.kotlinxCoroutines)
}

在 Gradle 文档的依赖管理基础中了解更多。

使用约定插件

高级

使用约定插件来封装并复用多个构建文件中的公共构建逻辑。把共享配置移到插件中，有助于简化和模块化你的构建脚本。

虽然初始设置可能比较耗时，但完成之后维护和添加新的构建逻辑就很容易了。

在 Gradle 文档的约定插件中了解更多。

优化

本节提供提升 Gradle 构建性能与效率的策略。

使用本地构建缓存

使用本地构建缓存，通过复用其他构建产生的输出来节省时间。构建缓存可以取用你已经创建过的任何更早构建的输出。

在 Gradle 文档的构建缓存中了解更多。

使用配置缓存

注意： 配置缓存目前尚未支持所有 Gradle 核心插件。最新信息请参阅 Gradle 的受支持插件表。

使用配置缓存，通过缓存配置阶段的结果并在后续构建中复用来显著提升构建性能。如果 Gradle 检测到构建配置或相关依赖没有变化，就会跳过配置阶段。

配置缓存还支持在单个项目内并行执行相互独立的任务，这可以进一步提升构建性能。此外，它会隐式启用 org.gradle.parallel 属性，让不同项目中的任务可以并行执行。

在 Gradle 文档中进一步了解配置缓存。

缩短多目标的构建时间

当你的多平台项目包含多个目标时，build 和 assemble 这类任务可能会为每个目标重复编译同一份代码，导致编译时间更长。

如果你正在针对某个特定平台积极开发和测试，请改为运行对应的 linkDebug* 任务。

更多信息请参阅缩短编译时间的技巧。

从 kapt 迁移到 KSP

如果你使用的库依赖 kapt 编译器插件，请检查是否可以改用 Kotlin Symbol Processing (KSP) API。KSP API 通过减少注解处理时间来提升构建性能。KSP 比 kapt 更快、更高效，因为它直接处理源代码，而不生成中间的 Java 桩文件。

关于迁移步骤的指导，请参阅迁移指南。

使用模块化

高级

注意： 模块化只对中等规模及以上的项目有益。对于基于微服务架构的项目，它不会带来优势。

使用模块化的项目结构来提升构建速度并便于并行开发。把你的项目组织为一个根项目和一个或多个子项目。如果改动只影响其中一个子项目，Gradle 只会重新构建那个特定的子项目。

.
└── root-project/
    ├── settings.gradle.kts
    ├── app subproject/
    │   └── build.gradle.kts
    └── lib subproject/
        └── build.gradle.kts

在 Gradle 文档的用 Gradle 组织项目结构中了解更多。

搭建 CI/CD

高级

搭建 CI/CD 流程，通过增量构建和缓存依赖来显著缩短构建时间。添加持久化存储或使用远程构建缓存即可获得这些好处。这个过程不必很耗时，因为有些服务商（例如 GitHub）几乎开箱即用地提供该服务。

浏览 Gradle 社区手册中关于在持续集成系统中使用 Gradle的内容。

使用远程构建缓存

高级

与本地构建缓存类似，远程构建缓存通过复用其他构建的输出来帮你节省时间。它可以取用任何人运行过的任何更早构建的任务输出，而不只是最近一次。

远程构建缓存使用缓存服务器在不同构建之间共享任务输出。例如，在带 CI/CD 服务器的开发环境中，服务器上的所有构建都会填充远程缓存。当你检出主分支开始开发新特性时，就能立即获得增量构建的好处。

请记住，网络连接较慢时，传输缓存结果可能比在本地运行任务更慢。

在 Gradle 文档的构建缓存中了解更多。