Android Gradle —— 从 Groovy 快速迁移到 Kotlin DSL

Kotlin 脚本 (KTS) 比 Groovy 更适合用于编写 Gradle 脚本，因为采用 Kotlin 编写的代码可读性更高，并且 Kotlin 提供了更好的编译时检查和 IDE 支持。Android Gradle 插件 4.0 支持在 Gradle build 配置中使用 KTS。

本页介绍了有关将 Android 应用的 Gradle build 文件从 Groovy 转换为 KTS 的基本信息。我们建议您按照所列顺序执行这些步骤。另请参阅 Gradle 的迁移指南和 Kotlin DSL Primer。 如果要迁移多个项目，请从最小的项目开始以便积累经验，然后再继续迁移。

常用术语

KTS：是指 Kotlin 脚本，这是 Gradle 在 build 配置文件中使用的一种 Kotlin 语言形式。Kotlin 脚本是可从命令行运行的 Kotlin 代码。

Kotlin DSL：主要是指 Android Gradle 插件 Kotlin DSL，有时也指底层 Gradle Kotlin DSL。

在讨论从 Groovy 迁移时，术语“KTS”和“Kotlin DSL”可以互换使用。换句话说，“将 Android 项目从 Groovy 转换为 KTS”与“将 Android 项目从 Groovy 转换为 Kotlin DSL”实际上是一个意思。

脚本文件命名

脚本文件扩展名取决于编写 build 文件所用的语言：

• 用 Groovy 编写的 Gradle build 文件使用 .gradle 文件扩展名。
• 用 Kotlin 编写的 Gradle build 文件使用 .gradle.kts 文件扩展名。

准备工作

一些简单的 Kotlin 和 Groovy 语言差异可能会使转换脚本变得繁琐：

• Groovy 的字符串可以用单引号 ‘string’ 或双引号 “string” 引用，而 Kotlin 要求使用双引号 “string”。
• Groovy 允许省略调用函数时的括号，而 Kotlin 总是要求括号。
• Gradle Groovy DSL 允许在分配属性时省略 = 赋值运算符，而 Kotlin 总是需要赋值运算符。

首先，建议采取以下措施来准备您的 Groovy 构建脚本：

• 使用双引号统一引用样式
• 通过分别使用括号和赋值运算符来消除函数调用和属性分配的歧义。

您可以通过查找 ’ 并将其替换为 " 轻松完成引号的一致性修改。例如，

// build.gradle

group 'com.acme'
dependencies {
    implementation 'com.acme:example:1.0'
}

修改成:

// build.gradle

group "com.acme"
dependencies {
    implementation "com.acme:example:1.0"
}

后者稍微麻烦，因为在 Groovy 脚本中区分函数调用和属性分配可能并不容易。一个好的策略是首先将所有不确定的语句视作属性分配，然后通过将失败的语句更改为函数调用来修复构建。例如，

// build.gradle

group "com.acme"
dependencies {
    implementation "com.acme:example:1.0"
}

修改成:

// build.gradle

group = "com.acme"                            // 赋值               
dependencies {
    implementation("com.acme:example:1.0")    // 函数调用
}

虽然这种方式仍然符合有效的 Groovy 语法，但现在已经消除了歧义，并且非常接近 Kotlin 的语法，这使得更名脚本以将其转换为 Gradle Kotlin DSL 脚本变得更加容易。

插件相关迁移

使用插件

与 Groovy DSL 类似，使用 Gradle 插件有两种方式：

• 通过 plugins {} 块进行声明式应用
• 通过旧版的 apply(..) 函数进行命令式应用

以下是使用声明式 plugins {} 块的示例:

// build.gradle.kts

plugins {
    java
    jacoco
    `maven-publish`
    id("org.springframework.boot") version "2.7.5"
}

Kotlin DSL 为所有 Gradle核心插件 提供了属性扩展，如上面的 java、jacoco 或 maven-publish 声明所示。

第三方插件可以以与 Groovy DSL 相同的方式应用，除了双引号和括号的用法不同。您也可以使用该样式来应用核心插件。但是，推荐使用静态类型访问器，因为它们是类型安全的，并且将通过您的 IDE 自动完成。

您也可以使用命令式的 apply 语法，但此时非核心插件必须包含在构建脚本的类路径中：

// build.gradle.kts

buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:2.7.5")
    }
}

apply(plugin = "java")
apply(plugin = "jacoco")
apply(plugin = "org.springframework.boot")

我们强烈建议您优先使用 plugins {} 块，而非 apply() 函数。

plugins {} 块的声明性质使 Kotlin DSL 能够提供类型安全的访问器，以访问应用插件所提供的扩展、配置和其他特性，使 IDE 能够轻松发现插件模型的详细信息并轻松配置它们。

请参阅 Gradle 用户手册中的 plugins {} 块文档，以获取更多信息。

配置插件

许多插件都具有用于配置它们的扩展。如果使用声明式 plugins {} 块应用这些插件，则会提供 Kotlin 扩展函数来配置它们的扩展，就像在 Groovy 中一样。以下示例展示了如何对 Jacoco 插件进行配置：

// build.gradle.kts

plugins {
    jacoco
}

jacoco {
    toolVersion = "0.8.1"
}

相比之下，如果您使用命令式的 apply() 函数来应用插件，则必须使用 configure<T>() 函数来配置该插件。以下示例演示了如何明确声明插件的扩展类（CheckstyleExtension），并将其传递给 configure<T>() 函数，以配置 Checkstyle 插件：

// build.gradle.kts

apply(plugin = "checkstyle")

configure<CheckstyleExtension> {
    maxErrors = 10
}

再次强烈建议您通过 plugins {} 块以声明性方式应用插件。

了解可用的 插件 扩展

由于 IDE 知道插件提供的配置元素，因此在您要求 IDE 提供建议时，它将包括那些元素。这将在构建脚本顶层（大多数插件扩展都添加到 Project 对象中）以及扩展配置块内部发生。

您还可以运行 :kotlinDslAccessorsReport 任务，以了解所有应用插件提供的扩展。它会打印出您可以使用的 Kotlin 代码来访问这些扩展，并提供访问器方法的名称和类型。

如果您想要配置的插件在其方法签名中依赖于 groovy.lang.Closure 或使用其他动态 Groovy 语义，那么就需要在 Kotlin DSL 构建脚本中进行更多的工作来配置该插件。有关如何从 Kotlin 代码中调用 Groovy 代码或在 Groovy 脚本中保留该插件配置的更多信息，请参见本文档中的 互操作性 部分。