将构建逻辑从 Groovy 迁移到 Kotlin

本节将引导您将基于 Groovy 的 Gradle 构建脚本转换为 Kotlin。

Gradle 新的 Kotlin DSL 在受支持的 IDE 中提供愉快的编辑体验：内容辅助、重构、文档等。

另请阅读 Gradle Kotlin DSL Primer，以了解 Gradle Kotlin DSL 的特性、限制和用法。

用户手册的其余部分包含构建脚本摘录，这些摘录演示了 Groovy DSL 和 Kotlin DSL。这是查找如何使用每种 DSL 以及如何实现 Gradle 所有功能（从使用插件到自定义依赖项解析行为）的最佳位置。

开始迁移之前

请阅读：在迁移之前，了解以下重要信息会很有帮助

首先应该使用最新版本的 Gradle、应用的插件和您的 IDE。
IntelliJ IDEA 和 Android Studio 完全支持 Kotlin DSL。其他 IDE，例如 Eclipse 或 NetBeans，尚未提供用于编辑 Gradle Kotlin DSL 文件的有用工具，但是，导入和使用基于 Kotlin DSL 的构建可以正常进行。
在 IntelliJ IDEA 中，您必须从 Gradle 模型导入项目，才能获得 Kotlin DSL 脚本的内容辅助和重构工具。
在某些情况下，Kotlin DSL 较慢。例如，首次使用、全新检出或临时 CI 代理，已知速度较慢。同样，如果 buildSrc 目录中的某些内容发生更改，导致构建脚本缓存失效，也会出现这种情况。构建配置时间过长可能会影响 IDE 响应速度，请查看Gradle 性能文档。
您必须使用 Java 8 或更高版本运行 Gradle。不支持 Java 7。
嵌入式 Kotlin 编译器已知可在 x86-64 架构的 Linux、macOS、Windows、Cygwin、FreeBSD 和 Solaris 上运行。
了解 Kotlin 语法和基本语言特性非常有帮助。Kotlin 参考文档和Kotlin Koans应该对您有用。
使用 plugins {} 块声明 Gradle 插件显著改善了编辑体验，强烈推荐。在将 Groovy 构建脚本转换为 Kotlin 之前，请考虑采用它。
Kotlin DSL 不支持 model {} 元素。这是已停用的 Gradle 软件模型的一部分。
不建议启用孵化中的按需配置功能，因为它可能导致难以诊断的问题。

在 Gradle Kotlin DSL Primer 中阅读更多内容。

如果您遇到问题或疑似错误，请利用 gradle/gradle 问题跟踪器。

您不必一次性全部迁移！基于 Groovy 和 Kotlin 的构建脚本都可以 apply 任何语言的其他脚本。您可以在 Kotlin DSL 示例中找到未涵盖的任何 Gradle 功能的灵感。

准备 Groovy 脚本

一些简单的 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"                          (1)
dependencies {
    implementation("com.acme:example:1.0")  (2)
}

1	属性赋值
2	函数调用

在保持 Groovy 有效的同时，它现在变得明确且接近 Kotlin 语法，使其更容易重命名脚本以将其转换为 Gradle Kotlin DSL 脚本。

重要的是要注意，虽然 Groovy 额外属性可以使用对象的 ext 属性进行修改，但在 Kotlin 中，它们使用 extra 属性进行修改。检查每个对象并相应地更新构建脚本非常重要。

您可以在用户指南中找到一个示例。

脚本文件命名

Groovy DSL 脚本文件使用 .gradle 文件扩展名。Kotlin DSL 脚本文件使用 .gradle.kts 文件扩展名。

要使用 Kotlin DSL，只需将文件命名为 build.gradle.kts 而不是 build.gradle。

设置文件 settings.gradle 也可以重命名为 settings.gradle.kts。

在多项目构建中，您可以有一些模块使用 Groovy DSL（带 build.gradle），而另一些模块使用 Kotlin DSL（带 build.gradle.kts）。

此外，应用以下约定以获得更好的 IDE 支持

根据模式 *.settings.gradle.kts 命名应用于 Settings 的脚本，
根据模式 *.init.gradle.kts 命名初始化脚本。

应用插件

与 Groovy DSL 一样，有两种方法可以应用 Gradle 插件

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

build.gradle.kts

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

build.gradle

plugins {
    id 'java'
    id 'jacoco'
    id 'maven-publish'
    id 'org.springframework.boot' version '3.4.4'
}

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:3.4.4")
    }
}

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

build.gradle

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

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"
}

build.gradle

plugins {
    id 'jacoco'
}

jacoco {
    toolVersion = '0.8.1'
}

相比之下，如果您使用命令式 apply() 函数应用插件，则必须使用 configure() 函数来配置该插件。以下示例演示了 Checkstyle 插件如何通过在 configure() 函数中显式声明插件的扩展类（即 CheckstyleExtension）来实现此目的

build.gradle.kts

apply(plugin = "checkstyle")

configure<CheckstyleExtension> {
    maxErrors = 10
}

build.gradle

apply plugin: "checkstyle"

checkstyle {
    maxErrors = 10
}

再次强调，我们强烈建议您通过 plugins {} 块声明性地应用插件。

了解可用的插件提供的扩展

因为您的 IDE 了解插件提供的配置元素，所以在您向 IDE 请求建议时，它会包含这些元素。这将在构建脚本的顶层（大多数插件扩展都添加到 Project 对象）以及扩展的配置块中发生。

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

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

插件还贡献了您可能想要直接配置的任务。此主题在下面的配置任务部分中介绍。

保持构建脚本的声明性

为了获得 Gradle Kotlin DSL 的最大好处，您应该努力保持构建脚本的声明性。这里要记住的主要一点是，为了获得类型安全访问器，插件必须在构建脚本主体之前应用。

强烈建议阅读 Gradle 用户手册中关于使用 Gradle Kotlin DSL配置插件的内容。

如果您的构建是多项目构建（例如大多数 Android 构建），请同时阅读有关多项目构建的后续部分。

最后，有一些策略可以将 plugins {} 块与未发布正确元数据（例如 Android Gradle 插件）的插件一起使用。

配置规避

Gradle 4.9 引入了一个新的 API，用于在构建脚本和插件中创建和配置任务。其目的是让这个新 API 最终取代现有 API。

现有 Gradle Tasks API 与新 API 之间的主要区别之一是 Gradle 是否花费时间创建 Task 实例并运行配置代码。新 API 允许 Gradle 延迟或完全避免配置在构建中永远不会执行的任务。例如，在编译代码时，Gradle 不需要配置运行测试的任务。

有关更多信息，请参阅演进 Gradle API 以减少配置时间博客文章和用户手册中的任务配置规避章节。

Gradle Kotlin DSL 采纳了配置规避，通过使类型安全模型访问器利用新 API 并提供 DSL 构造来使其更易于使用。请放心，整个 Gradle API 仍然可用。

配置任务

配置任务的语法是 Groovy 和 Kotlin DSL 开始显著不同的地方。

在 Kotlin 中，任务被命名空间到 tasks 容器中

build.gradle.kts

tasks.jar {
    archiveFileName = "foo.jar"
}

build.gradle

tasks.jar {
    archiveFileName = 'foo.jar'
}

请注意，在 Kotlin 中，tasks.jar {} 符号利用了配置规避 API，并推迟了 jar 任务的配置。

如果类型安全任务访问器 tasks.jar 不可用，请参阅上面的配置插件部分，您可以回退到使用 tasks 容器 API。以下示例的 Kotlin 版本与上面使用类型安全访问器的版本严格等效

使用 tasks 容器 API

build.gradle.kts

tasks.named<Jar>("jar") {
    archiveFileName = "foo.jar"
}

build.gradle

tasks.named('jar') {
    archiveFileName = 'foo.jar'
}

请注意，由于 Kotlin 是一种静态类型语言，因此有必要显式指定任务的类型。否则，脚本将无法编译，因为推断类型将是 Task，而不是 Jar，并且 archiveName 属性是 Jar 任务类型特有的。

如果配置规避在迁移过程中阻碍了您，并且您希望像 Groovy 一样急切地配置任务，则可以通过在 tasks 容器上使用急切配置 API 来实现

使用 tasks 容器 API 进行急切配置

build.gradle.kts

tasks.getByName<Jar>("jar") {
    archiveFileName = "foo.jar"
}

build.gradle

tasks.getByName('jar') {
    archiveFileName = 'foo.jar'
}

在 Gradle Kotlin DSL 中使用容器的详细文档在此处。

了解任务类型

如果您不知道任务的类型，可以通过内置的 help 任务来查找。只需使用 --task 选项将您感兴趣的任务名称传递给它，如下所示

❯ ./gradlew help --task jar
...
Type
     Jar (org.gradle.api.tasks.bundling.Jar)

让我们通过一个快速工作示例将所有这些结合起来，该示例配置 Spring Boot 项目的 bootJar 和 bootRun 任务

使用类型安全访问器配置 Spring Boot

build.gradle.kts

plugins {
    java
    id("org.springframework.boot") version "3.4.4"
}

tasks.bootJar {
    archiveFileName = "app.jar"
    mainClass = "com.example.demo.Demo"
}

tasks.bootRun {
    mainClass = "com.example.demo.Demo"
    args("--spring.profiles.active=demo")
}

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.4.4'
}

tasks.bootJar {
    archiveFileName = 'app.jar'
    mainClass = 'com.example.demo.Demo'
}

tasks.bootRun {
    mainClass = 'com.example.demo.Demo'
    args '--spring.profiles.active=demo'
}

这很容易理解。主要区别在于，当使用 Kotlin DSL 访问器时，任务配置会自动变为惰性。

现在，为了示例的目的，让我们看一下使用 API 而不是类型安全访问器应用的相同配置，这些访问器可能不可用，具体取决于构建逻辑结构，有关更多信息，请参阅 Gradle 用户手册中相应的文档。

我们首先通过 help 任务确定 bootJar 和 bootRun 任务的类型

❯ ./gradlew help --task bootJar
...
Type
     BootJar (org.springframework.boot.gradle.tasks.bundling.BootJar)

❯ ./gradlew help --task bootRun
...
Type
     BootRun (org.springframework.boot.gradle.tasks.run.BootRun)

现在我们知道这两个任务的类型了，我们可以导入相关类型（BootJar 和 BootRun）并根据需要配置任务。请注意，IDE 可以帮助我们进行所需的导入，因此我们只需要简单的名称，即不带完整包的名称。以下是生成的构建脚本，包含导入内容

使用 API 配置 Spring Boot

build.gradle.kts

import org.springframework.boot.gradle.tasks.bundling.BootJar
import org.springframework.boot.gradle.tasks.run.BootRun

// TODO:Finalize Upload Removal - Issue #21439
plugins {
    java
    id("org.springframework.boot") version "3.4.4"
}

tasks.named<BootJar>("bootJar") {
    archiveFileName = "app.jar"
    mainClass = "com.example.demo.Demo"
}

tasks.named<BootRun>("bootRun") {
    mainClass = "com.example.demo.Demo"
    args("--spring.profiles.active=demo")
}

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.4.4'
}

tasks.named('bootJar') {
    archiveFileName = 'app.jar'
    mainClass = 'com.example.demo.Demo'
}

tasks.named('bootRun') {
    mainClass = 'com.example.demo.Demo'
    args '--spring.profiles.active=demo'
}

创建任务

可以使用名为 task(…) 的脚本顶层函数创建任务

使用顶层 tasks(…) 函数

build.gradle.kts

task("greeting") {
    doLast { println("Hello, World!") }
}

build.gradle

task greeting {
    doLast { println 'Hello, World!' }
}

请注意，上述内容急切地配置了使用 Groovy 和 Kotlin DSL 创建的任务。

任务的注册或创建也可以在 tasks 容器上进行，分别使用 register(…) 和 create(…) 函数，如下所示

使用配置规避 API 和 DSL

build.gradle.kts

tasks.register("greeting") {
    doLast { println("Hello, World!") }
}

build.gradle

tasks.register('greeting') {
    doLast { println('Hello, World!') }
}

使用急切 API 和 DSL

build.gradle.kts

tasks.create("greeting") {
    doLast { println("Hello, World!") }
}

build.gradle

tasks.create('greeting') {
    doLast { println('Hello, World!') }
}

上面的示例创建了无类型、临时任务，但您通常会希望创建特定类型的任务。这也可以使用相同的 register() 和 create() 方法来完成。这是一个创建新 Zip 类型任务的示例

使用配置规避 API 和 DSL

build.gradle.kts

tasks.register<Zip>("docZip") {
    archiveFileName = "doc.zip"
    from("doc")
}

build.gradle

tasks.register('docZip', Zip) {
    archiveFileName = 'doc.zip'
    from 'doc'
}

使用急切 API 和 DSL

build.gradle.kts

tasks.create<Zip>("docZip") {
    archiveFileName = "doc.zip"
    from("doc")
}

build.gradle

tasks.create(name: 'docZip', type: Zip) {
    archiveFileName = 'doc.zip'
    from 'doc'
}

配置和依赖项

在现有配置中声明依赖项与 Groovy 构建脚本中的方式类似，您可以在此示例中看到

build.gradle.kts

plugins {
    `java-library`
}
dependencies {
    implementation("com.example:lib:1.1")
    runtimeOnly("com.example:runtime:1.0")
    testImplementation("com.example:test-support:1.3") {
        exclude(module = "junit")
    }
    testRuntimeOnly("com.example:test-junit-jupiter-runtime:1.3")
}

build.gradle

plugins {
    id 'java-library'
}
dependencies {
    implementation 'com.example:lib:1.1'
    runtimeOnly 'com.example:runtime:1.0'
    testImplementation('com.example:test-support:1.3') {
        exclude(module: 'junit')
    }
    testRuntimeOnly 'com.example:test-junit-jupiter-runtime:1.3'
}

每个由已应用插件贡献的配置也作为 configurations 容器的成员可用，因此您可以像引用任何其他配置一样引用它。

了解可用的配置

了解可用配置的最简单方法是在 configurations 容器内向 IDE 寻求建议。

您还可以使用 :kotlinDslAccessorsReport 任务，它会打印用于访问已应用插件贡献的配置的 Kotlin 代码，并提供所有这些访问器的名称。

请注意，如果您不使用 plugins {} 块来应用您的插件，那么您将无法以通常的方式配置这些插件提供的依赖项配置。相反，您将不得不使用字符串字面量作为配置名称，这意味着您将无法获得 IDE 支持

build.gradle.kts

apply(plugin = "java-library")
dependencies {
    "implementation"("com.example:lib:1.1")
    "runtimeOnly"("com.example:runtime:1.0")
    "testImplementation"("com.example:test-support:1.3") {
        exclude(module = "junit")
    }
    "testRuntimeOnly"("com.example:test-junit-jupiter-runtime:1.3")
}

build.gradle

apply plugin: 'java-library'
dependencies {
    implementation 'com.example:lib:1.1'
    runtimeOnly 'com.example:runtime:1.0'
    testImplementation('com.example:test-support:1.3') {
        exclude(module: 'junit')
    }
    testRuntimeOnly 'com.example:test-junit-jupiter-runtime:1.3'
}

这只是一个更多理由，无论何时，您都应该使用 plugins {} 块！

自定义配置和依赖项

有时您需要创建自己的配置并向其附加依赖项。以下示例声明了两个新配置

db，我们向其中添加了 PostgreSQL 依赖项
integTestImplementation，它被配置为扩展 testImplementation 配置，我们向其中添加了不同的依赖项

build.gradle.kts

val db by configurations.creating
val integTestImplementation by configurations.creating {
    extendsFrom(configurations["testImplementation"])
}

dependencies {
    db("org.postgresql:postgresql")
    integTestImplementation("com.example:integ-test-support:1.3")
}

build.gradle

configurations {
    db
    integTestImplementation {
        extendsFrom testImplementation
    }
}

dependencies {
    db 'org.postgresql:postgresql'
    integTestImplementation 'com.example:integ-test-support:1.3'
}

请注意，在上述示例中，我们只能在 dependencies {} 块中使用 db(…) 和 integTestImplementation(…) 标记，因为这两个配置都是预先通过 creating() 方法声明为委托属性的。如果配置是在其他地方定义的，您只能通过首先通过 configurations（而不是 configurations.creating()）创建委托属性，或者通过在 dependencies {} 块中使用字符串文字来引用它们。以下示例演示了这两种方法

build.gradle.kts

// get the existing 'testRuntimeOnly' configuration
val testRuntimeOnly by configurations

dependencies {
    testRuntimeOnly("com.example:test-junit-jupiter-runtime:1.3")
    "db"("org.postgresql:postgresql")
    "integTestImplementation"("com.example:integ-test-support:1.3")
}

迁移策略

如上所述，使用 Kotlin DSL 和 Groovy DSL 的脚本都可以参与同一个构建。此外，来自 buildSrc 目录、包含的构建或外部位置的 Gradle 插件可以使用任何 JVM 语言实现。这使得逐步、分批地迁移构建成为可能，而不会阻碍您的团队。

两种迁移方法脱颖而出

在保留结构的同时，将现有构建语法一点一点地迁移到 Kotlin——我们称之为机械迁移
将构建逻辑重构为 Gradle 最佳实践，并将切换到 Kotlin DSL 作为该工作的一部分

这两种方法都是可行的。机械迁移对于简单的构建就足够了。一个复杂且高度动态的构建可能无论如何都需要一些重构，因此在这种情况下，重新实现构建逻辑以遵循 Gradle 最佳实践是有意义的。

由于应用 Gradle 最佳实践将使您的构建更易于使用且速度更快，因此我们建议您最终以这种方式迁移所有项目，但首先关注需要重构的项目以及最能从改进中受益的项目是有意义的。

还要考虑，构建逻辑中对 Groovy 动态方面依赖的部分越多，从 Kotlin DSL 使用它们就越困难。无论动态 Groovy 构建逻辑位于何处，您都可以在Gradle Kotlin DSL 文档的互操作性部分中找到如何跨越静态 Kotlin 的动态边界的秘诀。

有两个关键的最佳实践可以更容易地在 Kotlin DSL 的静态上下文中工作

使用 plugins {} 块
将本地构建逻辑放入构建的 buildSrc 目录中

plugins {} 块旨在保持构建脚本的声明性，以便充分利用 Kotlin DSL。

利用buildSrc 项目旨在将构建逻辑组织成可轻松测试并提供良好 IDE 支持的共享本地插件和约定。

Kotlin DSL 构建结构示例

根据您的构建结构，您可能对以下用户手册章节感兴趣

编写构建脚本章节演示了如何使用 apply(from = "") 来模块化构建脚本。
多项目构建章节演示了各种多项目构建结构。
开发自定义 Gradle 插件和Gradle Kotlin DSL Primer章节演示了如何开发自定义 Gradle 插件。
组合构建章节演示了如何使用组合构建。

互操作性

在构建逻辑中混合语言时，您可能需要跨越语言边界。一个极端的例子是，一个构建使用用 Java、Groovy 和 Kotlin 实现的任务和插件，同时还使用 Kotlin DSL 和 Groovy DSL 构建脚本。

引用 Kotlin 参考文档

Kotlin 在设计时就考虑到了 Java 互操作性。现有的 Java 代码可以自然地从 Kotlin 调用，Kotlin 代码也可以相当流畅地从 Java 使用。

Kotlin 参考文档中很好地涵盖了从 Kotlin 调用 Java 和从 Java 调用 Kotlin。

同样也适用于与 Groovy 代码的互操作性。此外，Kotlin DSL 提供了几种方法来选择 Groovy 语义。

关于 Gradle Kotlin DSL 和互操作性

请在 Gradle Kotlin DSL Primer 的互操作性部分中找到详细文档。

此页面有帮助吗？