Kotlin 2.1.0 中的新功能

IDE 支持

最新的 IntelliJ IDEA 和 Android Studio 中绑定了支持 2.1.0 的 Kotlin plugin. 你不需要在你的 IDE 中更新 Kotlin plugin. 你需要做的只是在你的构建脚本中修改 Kotlin 版本为 2.1.0.

语言

带主语(Subject)的 when 中的保护条件(Guard Condition)

从 2.1.0 开始, 你可以在带主语(Subject)的 when 表达式或语句中使用保护条件(Guard Condition).

保护条件允许你在 when 表达式的分支中包含一个以上的条件, 让复杂的控制流变得更加明确和简洁, 并使代码结构更加扁平.

要在一个分支中包含保护条件, 请将它放在主条件之后, 用 if 分隔:

sealed interface Animal {
    data class Cat(val mouseHunter: Boolean) : Animal {
        fun feedCat() {}
    }

    data class Dog(val breed: String) : Animal {
        fun feedDog() {}
    }
}

fun feedAnimal(animal: Animal) {
    when (animal) {
        // 只带有主条件的分支. 当 `animal` 是 `Dog` 时, 调用 `feedDog()`
        is Animal.Dog -> animal.feedDog()
        // 带有主条件和保护条件的分支. 当 `animal` 是 `Cat`, 并且不是 `mouseHunter` 时, 调用 `feedCat()`
        is Animal.Cat if !animal.mouseHunter -> animal.feedCat()
        // 如果上面的条件都不成立, 打印输出 "Unknown animal"
        else -> println("Unknown animal")
    }
}

在单个 when 表达式中, 你可以组合使用带有保护条件和不带保护条件的分支. 带有保护条件的分支中的代码, 只有在主条件和保护条件的计算结果都为 true 时才会运行. 如果主条件不成立, 那么保护条件不会被计算. 此外, 保护条件支持 else if.

kotlinc -Xwhen-guards main.kt

或者, 将它添加到你的 Gradle 构建文件的 compilerOptions {} 代码块:

// build.gradle.kts
kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xwhen-guards")
    }
}

非局部的(non-local) break 和 continue

Kotlin 2.1.0 添加了另一个期待已久的功能的预览版, 允许使用非局部的(non-local) break 和 continue. 这个功能扩展了你在内联函数范围内能够使用的工具集, 并减少你的项目中的样板代码.

以前, 你只能使用非局部的(non-local) 返回. 现在, Kotlin 还支持非局部的 break 和 continue 跳转表达式. 这就意味着, 对于包含循环的内联函数, 在作为参数传递给这个内联函数的 Lambda 表达式中, 你可以使用它们:

fun processList(elements: List<Int>): Boolean {
    for (element in elements) {
        val variable = element.nullableMethod() ?: run {
            log.warning("Element is null or invalid, continuing...")
            continue
        }
        if (variable == 0) return true // 如果 variable 为 0, 返回 true
    }
    return false
}

要在你的项目中试用这个功能, 请在命令行中使用 -Xnon-local-break-continue 编译器选项:

kotlinc -Xnon-local-break-continue main.kt

或者, 将它添加到你的 Gradle 构建文件的 compilerOptions {} 代码块:

// build.gradle.kts
kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xnon-local-break-continue")
    }
}

我们计划在将来的 Kotlin 发布版中让这个功能进入稳定版. 如果你在使用非局部的 break 和 continue 时遇到任何问题, 请在我们的问题追踪系统中报告问题.

多 `$` 符号字符串插值(Interpolation)

Kotlin 2.1.0 引入了对多 $ 符号字符串插值(Interpolation)的支持, 它改进了字符串字面值中对 $ 符号的处理方式. 这个功能对需要使用多个 $ 符号的情况很有帮助, 例如模板引擎, JSON 模式, 或其它数据格式.

Kotlin 中的字符串插值使用单个 $ 符号. 但是, 在字符串中将 $ 符号用作字面值, (这是财物数据和模板系统中的常见情况), 会需要变通方法, 例如 ${'$'}. 启用多 $ 符号插值功能后, 你就可以配置需要多少个 $ 符号来触发插值, 较少的 $ 符号会被当做字符串字面值.

下面是一个示例, 演示如何生成 JSON 模式的多行字符串, 其中带有使用 $ 的占位符:

val KClass<*>.jsonSchema : String
    get() = $$"""
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "$id": "https://example.com/product.schema.json",
      "$dynamicAnchor": "meta"
      "title": "$${simpleName ?: qualifiedName ?: "unknown"}",
      "type": "object"
    }
    """

这个示例中, $$ 前缀表示你需要 2 个 $ 符号 ($$) 来触发插值. 它会阻止 $schema, $id, 和 $dynamicAnchor 被翻译为插值标记.

在处理那些占位符语法中使用 $ 符号的系统时, 这种方法非常有帮助.

kotlinc -Xmulti-dollar-interpolation main.kt

或者, 更新你的 Gradle 构建文件的 compilerOptions {} 代码块:

// build.gradle.kts
kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xmulti-dollar-interpolation")
    }
}

如果你的代码已经使用了标准的单个 $ 符号的字符串插值, 那么不需要任何变更. 你可以在字符串中需要 $ 符号字面值时, 使用 $$.

支持对扩展 API (extend API) 要求使用者同意

要对一个 API 元素添加使用者同意的要求, 请使用 @SubclassOptInRequired 注解, 其中指定注解类的引用:

@RequiresOptIn(
level = RequiresOptIn.Level.WARNING,
message = "Interfaces in this library are experimental"
)
annotation class UnstableApi()

@SubclassOptInRequired(UnstableApi::class)
interface CoreLibraryApi

这个示例中, CoreLibraryApi 接口要求使用者同意, 然后才可以实现它. 使用者可以这样表示使用者同意:

@OptIn(UnstableApi::class)
interface MyImplementation: CoreLibraryApi

关于如何在你的 API 中使用 @SubclassOptInRequired 注解的真实示例, 请参见 kotlinx.coroutines 库中的 SharedFlow 接口.

改进了对带有泛型类型的函数的重载(overload)解析

class KeyValueStore<K, V> {
    fun store(key: K, value: V) {} // 重载函数 1
    fun store(key: K, lazyValue: () -> V) {} // 重载函数 2
}

fun <K, V> KeyValueStore<K, V>.storeExtension(key: K, value: V) {} // 重载函数 1
fun <K, V> KeyValueStore<K, V>.storeExtension(key: K, lazyValue: () -> V) {} // 重载函数 2

fun test(kvs: KeyValueStore<String, Int>) {
    // 成员函数
    kvs.store("", 1)    // 解析到重载函数 1
    kvs.store("") { 1 } // 解析到重载函数 2

    // 扩展函数
    kvs.storeExtension("", 1)    // 解析到重载函数 1
    kvs.storeExtension("") { 1 } // 无法解析
}

在这个示例中, KeyValueStore 类的 store() 函数有 2 个重载, 其中一个重载的函数参数是泛型类型 K 和 V, 另一个重载的参数是 Lambda 函数, 返回泛型类型 V. 类似的, 扩展函数 storeExtension() 也有 2 重载.

当使用和不使用 Lambda 函数来调用 store() 函数时, 编译器成功的解析到正确的重载函数. 但是, 当使用 Lambda 函数调用扩展函数 storeExtension() 时, 编译器不能解析到正确的重载, 因为它错误的认为 2 个重载都可以使用.

改进了使用封闭类的 when 表达式的穷尽检查

在 Kotlin 的以前版本中, 对于带有封闭上限(Sealed Upper Bound)的类型参数的 when 表达式, 即使已经覆盖了 sealed class 层级结构中的所有情况, 编译器仍然会要求 else 分支. 在 Kotlin 2.1.0 中, 已经解决并改善了这个问题, 使得穷尽检查更加强大, 并允许你删除不必要的 else 分支, 让 when 表达式更清晰, 更直观.

sealed class Result
object Error: Result()
class Success(val value: String): Result()

fun <T : Result> render(result: T) = when (result) {
    Error -> "Error!"
    is Success -> result.value
    // 不需要 else 分支
}

Kotlin K2 编译器

额外的编译器检查

检查类型	注释
`REDUNDANT_NULLABLE`	使用了 `Boolean??`, 而不是 `Boolean?`
`PLATFORM_CLASS_MAPPED_TO_KOTLIN`	使用了 `java.lang.String`, 而不是 `kotlin.String`
`ARRAY_EQUALITY_OPERATOR_CAN_BE_REPLACED_WITH_EQUALS`	使用了 `arrayOf("") == arrayOf("")`, 而不是 `arrayOf("").contentEquals(arrayOf(""))`
`REDUNDANT_CALL_OF_CONVERSION_METHOD`	使用了 `42.toInt()`, 而不是 `42`
`USELESS_CALL_ON_NOT_NULL`	使用了 `"".orEmpty()`, 而不是 `""`
`REDUNDANT_SINGLE_EXPRESSION_STRING_TEMPLATE`	使用了 `"$string"`, 而不是 `string`
`UNUSED_ANONYMOUS_PARAMETER`	一个参数传递给了 Lambda 表达式, 但未被使用
`REDUNDANT_VISIBILITY_MODIFIER`	使用了 `public class Klass`, 而不是 `class Klass`
`REDUNDANT_MODALITY_MODIFIER`	使用了 `final class Klass`, 而不是 `class Klass`
`REDUNDANT_SETTER_PARAMETER_TYPE`	使用了 `set(value: Int)`, 而不是 `set(value)`
`CAN_BE_VAL`	定义了 `var local = 0`, 但没有重新赋值, 可以改为使用 `val local = 42`
`ASSIGNED_VALUE_IS_NEVER_READ`	定义了 `val local = 42`, 但在之后的代码中没有使用
`UNUSED_VARIABLE`	定义了 `val local = 0`, 但在代码中没有使用
`REDUNDANT_RETURN_UNIT_TYPE`	使用了 `fun foo(): Unit {}`, 而不是 `fun foo() {}`
`UNREACHABLE_CODE`	存在代码语句, 但永远无法执行

额外检查默认禁用. 要启用这些检查, 请在命令行中使用 -Wextra 编译器选项, 或在你的 Gradle 构建文件的 compilerOptions {} 代码块中指定 extraWarnings:

// build.gradle.kts
kotlin {
    compilerOptions {
        extraWarnings.set(true)
    }
}

全局压制警告

现在你可以在整个项目中压制某个特定的警告, 方法是在命令行中使用 -Xsuppress-warning=WARNING_NAME 语法, 或者在你的构建文件的 compilerOptions {} 代码块中使用 freeCompilerArgs 属性.

// build.gradle.kts
kotlin {
    compilerOptions {
        extraWarnings.set(true)
        freeCompilerArgs.add("-Xsuppress-warning=CAN_BE_VAL")
    }
}

不允许压制错误.
如果你指定一个未知的警告名称, 编译会报告错误.

你可以一次性指定多个警告:

命令行

构建文件

kotlinc -Xsuppress-warning=NOTHING_TO_INLINE -Xsuppress-warning=NO_TAIL_CALLS_FOUND main.kt

K2 kapt 实现的改善

要使用新的 K2 kapt plugin 实现, 启用它的方法与以前的 K2 kapt plugin 相同. 请向你的项目的 gradle.properties 文件添加以下选项:

kapt.use.k2=true

解析无符号类型与非基本类型之间的重载冲突

扩展函数的重载

fun Any.doStuff() = "Any"
fun UByte.doStuff() = "UByte"

fun main() {
    val uByte: UByte = UByte.MIN_VALUE
    uByte.doStuff() // 在 Kotlin 2.1.0 之前, 会发生重载解析歧义
}

在较早的版本中, 调用 uByte.doStuff() 会导致歧义, 因为 Any 和 UByte 的扩展都可以使用.

顶级函数的重载

fun doStuff(value: Any) = "Any"
fun doStuff(value: UByte) = "UByte"

fun main() {
    val uByte: UByte = UByte.MIN_VALUE
    doStuff(uByte) // 在 Kotlin 2.1.0 之前, 会发生重载解析歧义
}

类似的, 调用 doStuff(uByte) 也会发生歧义, 因为编译器无法决定应该使用 Any 还是 UByte 的版本. 在 2.1.0 中, 编译器现在能够正确处理这种情况, 通过优先使用更加具体的类型来解决歧义, 在这个例子中会使用 UByte.

Kotlin/JVM

JSpecify 可否为 null(Nullability) 不匹配诊断的严重性变更为 strict

对于 org.jspecify.annotations 中的可否为 null(Nullability) 注解, Kotlin 2.1.0 强制要求 strict 处理, 以改善与 Java 交互时的类型安全性.

从 Kotlin 2.1.0 开始, 默认将可否为 null 的不匹配问题从警告提升为错误. 这样可以确保在类型检查中强制使用 @NonNull 和 @Nullable 之类的注解, 预防运行期发生意外的可否为 null 问题.

@NullMarked 注解也会影响它的范围内的所有成员可否为 null, 使得你在使用被注解的 Java 代码时行为更加可预测.

// Java
import org.jspecify.annotations.*;
public class SomeJavaClass {
    @NonNull
    public String foo() { //...
    }

    @Nullable
    public String bar() { //...
    }
}

// Kotlin
fun test(sjc: SomeJavaClass) {
    // 访问一个非 null 的结果, 这样是允许的
    sjc.foo().length

    // 在默认的 strict 模式中会发生错误, 因为结果可能为 nullable
    // 要避免这个错误, 要改为使用 ?.length
    sjc.bar().length
}

你可以对这些注解手动控制诊断的严重性. 方法是使用 -Xnullability-annotations 编译器选项来选择一个模式:

Kotlin Multiplatform

Kotlin Multiplatform 中的 Gradle 隔离项目(Isolated Project) (预览版)

选项 1: 不启用隔离项目, 检查兼容性 – 要在不启用隔离项目功能的情况下, 检查 Kotlin Gradle plugin 的新模型的兼容性, 请在你的项目的 gradle.properties 文件中, 添加以下 Gradle 属性:
```
# gradle.properties
kotlin.kmp.isolated-projects.support=enable
```
选项 2: 启用隔离项目, 检查兼容性 – 在 Gradle 中启用隔离项目功能, 会自动配置 Kotlin Gradle plugin, 让它使用新的模型. 要启用隔离项目功能, 请设置系统属性. 这种情况下, 你不需要对你的项目添加 Kotlin Gradle plugin 的 Gradle 属性.

对 Swift 导出的基本支持

// build.gradle.kts
kotlin {
    iosX64()
    iosArm64()
    iosSimulatorArm64()

    @OptIn(ExperimentalSwiftExportDsl::class)
    swiftExport {
        // 根模块名称
        moduleName = "Shared"

        // 折叠规则(Collapse Rule)
        // 在生成的 Swift 代码中, 删除包前缀
        flattenPackage = "com.example.sandbox"

        // 导出外部模块
        export(project(":subproject")) {
            // 导出的模块的名称
            moduleName = "Subproject"
            // 导出的依赖项的折叠规则
            flattenPackage = "com.subproject.library"
        }
    }
}

编译器会自动生成所有需要的文件 (包括 swiftmodule 文件, 静态的 a 库, 以及头文件和 modulemap 文件), 并将这些文件复制到 App 的构建目录, 你可以在 Xcode 中访问这个目录.

如何启用 Swift 导出

向你的 gradle.properties 文件添加以下 Gradle 选项:

# gradle.properties
kotlin.experimental.swift-export.enabled=true

在 Xcode 中, 打开项目设置.
在 Build Phases 页面, 找到包含 embedAndSignAppleFrameworkForXcode task 的 Run Script 阶段.
调整脚本, 在运行脚本阶段使用 embedSwiftExportForXcode task:
```
./gradlew :<共用的模块名称>:embedSwiftExportForXcode
```

能够从任何主机发布 Kotlin 库

Kotlin 编译器会为发布 Kotlin 库生成 .klib artifact. 以前, 你可以从任何主机得到需要的 artifact, Apple 平台的编译目标除外, 它需要 Mac 机器. 这对针对 iOS, macOS, tvOS, 以及 watchOS 目标平台的 Kotlin Multiplatform 项目造成了特殊的限制.

Kotlin 2.1.0 消除了这个限制, 增加了对交叉编译的支持. 现在你可以使用任何主机来生成 .klib artifact, 这样能够大大简化 Kotlin 和 Kotlin Multiplatform 库的发布过程.

如何启用从任何主机发布库的功能

要在你的项目中试用交叉编译, 请向你的 gradle.properties 文件添加以下选项:

# gradle.properties
kotlin.native.enableKlibsCrossCompilation=true

支持不打包的(non-packed) klib

Kotlin 2.1.0 允许生成不打包的(non-packed) .klib 文件 artifact. 通过这个功能, 你可以直接配置对 klib 的依赖项, 而不必先解包它们.

如何设置你的项目

// build.gradle.kts
import org.jetbrains.kotlin.gradle.plugin.attributes.KlibPackaging
// ...
val resolvableConfiguration = configurations.resolvable("resolvable") {
    // 用于新的不打包配置:
    attributes.attribute(KlibPackaging.ATTRIBUTE, project.objects.named(KlibPackaging.NON_PACKED))

    // 用于之前的打包配置:
    attributes.attribute(KlibPackaging.ATTRIBUTE, project.objects.named(KlibPackaging.PACKED))
}

在你的项目构建目录中, 不打包的 .klib 文件, 使用之前的打包文件的生成路径. 而打包的 klib 现在生成到 build/libs 目录中.

./gradlew outgoingVariants

Kotlin/Native

Kotlin/Wasm

对增量编译的支持

在目前的设置中, 增量编译对 Wasm 编译目标默认禁用. 要启用增量编译, 请向你的项目的 local.properties 或 gradle.properties 文件添加以下内容:

# gradle.properties
kotlin.incremental.wasm=true

浏览器 APIs 移动到了独立的 kotlinx-browser 库

在这个发布版中, org.w3c.* 声明从 Kotlin/Wasm 标准库移动到了新的 kotlinx-browser 库. 这个库还包含其它 Web 相关的包, 例如 org.khronos.webgl, kotlin.dom, 和 kotlinx.browser.

要使用移动后的包中的声明, 你需要向你的项目的构建配置文件添加 kotlinx-browser 依赖项:

// build.gradle.kts
val wasmJsMain by getting {
    dependencies {
        implementation("org.jetbrains.kotlinx:kotlinx-browser:0.3")
    }
}

改善了 Kotlin/Wasm 的调试体验

向 wasmJs {} 编译器选项添加以下编译器选项:

// build.gradle.kts
kotlin {
    wasmJs {
        // ...

        compilerOptions {
            freeCompilerArgs.add("-Xwasm-debugger-custom-formatters")
        }
    }
}

在你的浏览器中启用自定义格式化器:
- 在 Chrome DevTools 中, 通过 Settings | Preferences | Console 设置:
- 在 Firefox DevTools 中, 通过 Settings | Advanced settings 设置:

改善了 Kotlin/Wasm 中的 JavaScript 数组互操作性

尽管 Kotlin/Wasm 的标准库为 JavaScript 数组提供了 JsArray<T> 类型, 但没有直接的方法将 JsArray<T> 转换为 Kotlin 的原生 Array 或 List 类型.

这个发布版引入了一个适配器函数, 能够自动将 JsArray<T> 转换到 Array<T>, 以及反向转换, 简化了数组操作.

下面是泛型类型之间转换的一个示例: Kotlin List<T> 和 Array<T> 与 JavaScript JsArray<T> 之间转换.

val list: List<JsString> =
    listOf("Kotlin", "Wasm").map { it.toJsString() }

// 使用 .toJsArray(), 将 List 或 Array 转换为 JsArray
val jsArray: JsArray<JsString> = list.toJsArray()

// 使用 .toArray() 和 .toList(), 转换回 Kotlin 类型
val kotlinArray: Array<JsString> = jsArray.toArray()
val kotlinList: List<JsString> = jsArray.toList()

还有类似的方法, 可以将类型数组转换为 Kotlin 中对应的类型(例如, IntArray 和 Int32Array). 更多详细信息和具体实现, 请参见 kotlinx-browser 代码仓库.

下面是类型数组之间转换的一个示例: Kotlin IntArray 与 JavaScript Int32Array 之间转换.

import org.khronos.webgl.*

    // ...

    val intArray: IntArray = intArrayOf(1, 2, 3)

    // 使用 .toInt32Array(), 将 Kotlin IntArray 转换为 JavaScript Int32Array
    val jsInt32Array: Int32Array = intArray.toInt32Array()

    // 使用 toIntArray(), 将 JavaScript Int32Array 转换回 Kotlin IntArray
    val kotlinIntArray: IntArray = jsInt32Array.toIntArray()

在 Kotlin/Wasm 中支持访问 JavaScript 异常的详细信息

以前, 在 Kotlin/Wasm 中发生 JavaScript 异常时, JsException 类型只提供一个粗略的消息, 不包含原始的 JavaScript 错误的详细信息.

从 Kotlin 2.1.0 开始, 你可以启用一个特定的编译器选项来配置 JsException, 使它包含原始的错误消息, 和栈追踪(Stack Trace)信息. 这样可以提供更多上下文信息, 帮助诊断源自 JavaScript 的问题.

这个行为依赖于 WebAssembly.JSTag API, 这个 API 只能在特定的浏览器中使用:

这个功能默认禁用, 要启用这个功能, 请向你的 build.gradle.kts 文件添加以下编译器选项:

// build.gradle.kts
kotlin {
    wasmJs {
        compilerOptions {
            freeCompilerArgs.add("-Xwasm-attach-js-exception")
        }
    }
}

external object JSON {
    fun <T: JsAny> parse(json: String): T
}

fun main() {
    try {
        JSON.parse("an invalid JSON")
    } catch (e: JsException) {
        println("Thrown value is: ${e.thrownValue}")
        // 输出结果为: SyntaxError: Unexpected token 'a', "an invalid JSON" is not valid JSON

        println("Message: ${e.message}")
        // 输出结果为: Message: Unexpected token 'a', "an invalid JSON" is not valid JSON

        println("Stacktrace:")
        // 输出结果为: Stacktrace:

        // 打印输出完整的 JavaScript 栈追踪
        e.printStackTrace()
    }
}

启用 -Xwasm-attach-js-exception 选项后, JsException 类型会提供来自 JavaScript 错误的详细信息. 如果不启用这个选项, JsException 只包含粗略的信息, 表示在运行 JavaScript 代码时抛出了异常.

子项目特定的 Node.js 设置

你可以对 rootProject 定义 NodeJsRootPlugin 类的属性, 来为你的项目配置 Node.js 设置. 在 2.1.0 中, 你可以使用一个新的类 NodeJsPlugin, 对每个子项目配置这些设置. 下面是一个示例, 演示如何对一个子项目设置一个特定的 Node.js 版本:

// build.gradle.kts
project.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsPlugin> {
    project.the<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsEnvSpec>().version = "22.0.0"
}

要对整个项目使用新的类, 请在 allprojects {} 代码块中添加同样的代码:

// build.gradle.kts
allprojects {
    project.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsPlugin> {
        project.the<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsEnvSpec>().version = "你的 Node.js version"
    }
}

Kotlin/JS

在属性中支持非标识符字符

external interface Headers {
    var accept: String?

    // 无效的 Kotlin 标识符, 因为包含连字符
    var `content-length`: String?
}

val headers: Headers = TODO("value provided by a JS library")
val accept = headers.accept
// 发生错误, 因为属性名称中存在连字符
val length = headers.`content-length`

从 Kotlin 2.1.0 开始, 这个功能默认启用. Kotlin/JS 现在允许你使用反引号 (``) 和 @JsName 注解, 与包含非标识符字符的 JavaScript 属性交互, 并在测试方法名称中使用.

此外, 你可以使用 @JsName 和 @JsQualifier 注解, 将 Kotlin 属性名称映射到 JavaScript 中对应的部分:

object Bar {
    val `property example`: String = "bar"
}

@JsQualifier("fooNamespace")
external object Foo {
    val `property example`: String
}

@JsExport
object Baz {
    val `property example`: String = "bar"
}

fun main() {
    // 在 JavaScript 中, 被编译为 Bar.property_example_HASH
    println(Bar.`property example`)
    // 在 JavaScript 中, 被编译为 fooNamespace["property example"]
    println(Foo.`property example`)
    // 在 JavaScript 中, 被编译为 Baz["property example"]
    println(Baz.`property example`)
}

Gradle 改善

针对 Kotlin Gradle plugin 扩展的新 API

Kotlin 2.1.0 引入了一个新的 API, 可以更容易的创建你自己的 plugin, 来配置 Kotlin Gradle plugin. 这个变更废弃了 KotlinTopLevelExtension 和 KotlinTopLevelExtensionConfig 接口, 并为 plugin 开发者引入了以下接口:

名称	描述
`KotlinBaseExtension`	一个 plugin DSL 扩展类型, 用于对整个项目配置共通的 Kotlin JVM, Android, 和 Multiplatform plugin 选项: `org.jetbrains.kotlin.jvm` `org.jetbrains.kotlin.android` `org.jetbrains.kotlin.multiplatform`
`KotlinJvmExtension`	一个 plugin DSL 扩展类型, 用于对整个项目配置 Kotlin JVM plugin 选项.
`KotlinAndroidExtension`	一个 plugin DSL 扩展类型, 用于对整个项目配置 Kotlin Android plugin 选项.

名称

描述

KotlinBaseExtension

一个 plugin DSL 扩展类型, 用于对整个项目配置共通的 Kotlin JVM, Android, 和 Multiplatform plugin 选项:

org.jetbrains.kotlin.jvm
org.jetbrains.kotlin.android
org.jetbrains.kotlin.multiplatform

KotlinJvmExtension

一个 plugin DSL 扩展类型, 用于对整个项目配置 Kotlin JVM plugin 选项.

KotlinAndroidExtension

一个 plugin DSL 扩展类型, 用于对整个项目配置 Kotlin Android plugin 选项.

例如, 如果你想要对 JVM 和 Android 项目都配置编译器选项, 请使用 KotlinBaseExtension:

configure<KotlinBaseExtension> {
    if (this is HasConfigurableKotlinCompilerOptions<*>) {
        with(compilerOptions) {
            if (this is KotlinJvmCompilerOptions) {
                jvmTarget.set(JvmTarget.JVM_17)
            }
        }
    }
}

要只对 JVM 项目配置编译器选项, 请使用 KotlinJvmExtension:

configure<KotlinJvmExtension> {
    compilerOptions {
        jvmTarget.set(JvmTarget.JVM_17)
    }

    target.mavenPublication {
        groupId = "com.example"
        artifactId = "example-project"
        version = "1.0-SNAPSHOT"
    }
}

你可以通过完全相同的方式来使用 KotlinAndroidExtension.

编译器符号 hidden from the Kotlin Gradle plugin API

从 Kotlin 2.1.0 开始, 如果访问了 Kotlin Gradle plugin (KGP) 中捆绑的编译器模块符号, 你将收到一个警告. 以前, KGP 在它的运行期依赖项中包含了 org.jetbrains.kotlin:kotlin-compiler-embeddable, 导致内部的编译器符号, 例如 KotlinCompilerVersion, 在构建脚本类路径中可以访问. 这些符号本来的意图是只供内部使用.

使用 Gradle Workers API

// build.gradle.kts
dependencies {
    compileOnly("org.jetbrains.kotlin:kotlin-compiler-embeddable:2.1.0")
}

import org.gradle.workers.WorkAction
import org.gradle.workers.WorkParameters
import org.jetbrains.kotlin.config.KotlinCompilerVersion
abstract class ActionUsingKotlinCompiler : WorkAction<WorkParameters.None> {
    override fun execute() {
        println("Kotlin compiler version: ${KotlinCompilerVersion.getVersion()}")
    }
}

import org.gradle.api.DefaultTask
import org.gradle.api.file.ConfigurableFileCollection
import org.gradle.api.tasks.Classpath
import org.gradle.api.tasks.TaskAction
import org.gradle.workers.WorkerExecutor
import javax.inject.Inject
abstract class TaskUsingKotlinCompiler: DefaultTask() {
    @get:Inject
    abstract val executor: WorkerExecutor

    @get:Classpath
    abstract val kotlinCompiler: ConfigurableFileCollection

    @TaskAction
    fun compile() {
        val workQueue = executor.classLoaderIsolation {
            classpath.from(kotlinCompiler)
        }
        workQueue.submit(ActionUsingKotlinCompiler::class.java) {}
    }
}

import org.gradle.api.Plugin
import org.gradle.api.Project
abstract class MyPlugin: Plugin<Project> {
    override fun apply(target: Project) {
        val myDependencyScope = target.configurations.create("myDependencyScope")
        target.dependencies.add(myDependencyScope.name, "$KOTLIN_COMPILER_EMBEDDABLE:$KOTLIN_COMPILER_VERSION")
        val myResolvableConfiguration = target.configurations.create("myResolvable") {
            extendsFrom(myDependencyScope)
        }
        target.tasks.register("myTask", TaskUsingKotlinCompiler::class.java) {
            kotlinCompiler.from(myResolvableConfiguration)
        }
    }

    companion object {
        const val KOTLIN_COMPILER_EMBEDDABLE = "org.jetbrains.kotlin:kotlin-compiler-embeddable"
        const val KOTLIN_COMPILER_VERSION = "2.1.0"
    }
}

Compose 编译器的更新

支持多个稳定性配置文件

Compose 编译器能够理解多个稳定性配置文件, 但 Compose 编译器 Gradle plugin 的 stabilityConfigurationFile 选项以前只允许指定单个文件. 在 Kotlin 2.1.0 中, 修改了这个功能, 允许对单个模块使用多个稳定性配置文件:

// build.gradle.kt
composeCompiler {
    stabilityConfigurationFiles.addAll(
        project.layout.projectDirectory.file("configuration-file1.conf"),
        project.layout.projectDirectory.file("configuration-file2.conf"),
    )
}

可暂停的组合(Pausable composition)

// build.gradle.kts
composeCompiler {
    featureFlags = setOf(
        ComposeFeatureFlag.PausableComposition
    )
}

标准库

对 java.nio.file.Path 的文件树遍历扩展函数进入稳定版

Kotlin 1.7.20 为 java.nio.file.Path 类引入了实验性的扩展函数, 可以用来遍历一个文件树. 在 Kotlin 2.1.0 中, 以下文件树遍历扩展函数现在进入稳定版:

下面的示例演示如何使用这些文件遍历 API 来创建自定义的 FileVisitor 行为, 用来实现指定的动作访问文件和目录.

例如, 你可以明确创建一个 FileVisitor, 并在之后使用它:

val cleanVisitor = fileVisitor {
    onPreVisitDirectory { directory, attributes ->
        // 在这里添加访问目录的逻辑
        FileVisitResult.CONTINUE
    }

    onVisitFile { file, attributes ->
        // 在这里添加访问文件的逻辑
        FileVisitResult.CONTINUE
    }
}

// 在这里添遍历之前的一般设置逻辑
projectDirectory.visitFileTree(cleanVisitor)

你也可以使用 builderAction 创建一个 FileVisitor, 并立即使用它进行遍历:

projectDirectory.visitFileTree {
    // 定义 builderAction:
    onPreVisitDirectory { directory, attributes ->
        // 某些访问目录的逻辑
        FileVisitResult.CONTINUE
    }

    onVisitFile { file, attributes ->
        // 某些访问文件的逻辑
        FileVisitResult.CONTINUE
    }
}

另外, 你可以使用 walk() 函数, 遍历一个以指定的路径为根的文件树:

fun traverseFileTree() {
    val cleanVisitor = fileVisitor {
        onPreVisitDirectory { directory, _ ->
            if (directory.name == "build") {
                directory.toFile().deleteRecursively()
                FileVisitResult.SKIP_SUBTREE
            } else {
                FileVisitResult.CONTINUE
            }
        }

        // 删除扩展名为 .class 的文件
        onVisitFile { file, _ ->
            if (file.extension == "class") {
                file.deleteExisting()
            }
            FileVisitResult.CONTINUE
        }
    }

    // 设置根目录和文件
    val rootDirectory = createTempDirectory("Project")

    // 创建 src 目录, 包含 A.kt 和 A.class 文件
    rootDirectory.resolve("src").let { srcDirectory ->
        srcDirectory.createDirectory()
        srcDirectory.resolve("A.kt").createFile()
        srcDirectory.resolve("A.class").createFile()
    }

    // 创建 build 目录, 包含 Project.jar 文件
    rootDirectory.resolve("build").let { buildDirectory ->
        buildDirectory.createDirectory()
        buildDirectory.resolve("Project.jar").createFile()
    }

    // 使用 walk() 函数:
    val directoryStructure = rootDirectory.walk(PathWalkOption.INCLUDE_DIRECTORIES)
        .map { it.relativeTo(rootDirectory).toString() }
        .toList().sorted()
    println(directoryStructure)
    // 输出结果为: "[, build, build/Project.jar, src, src/A.class, src/A.kt]"

    // 使用 cleanVisitor 遍历文件树, 应用 rootDirectory.visitFileTree(cleanVisitor) 清除规则
    val directoryStructureAfterClean = rootDirectory.walk(PathWalkOption.INCLUDE_DIRECTORIES)
        .map { it.relativeTo(rootDirectory).toString() }
        .toList().sorted()
    println(directoryStructureAfterClean)
    // 输出结果为: "[, src, src/A.kt]"
}

Kotlin 2.1.0 中的新功能﻿

IDE 支持﻿

语言﻿

tip

带主语(Subject)的 when 中的保护条件(Guard Condition)﻿

warning

非局部的(non-local) break 和 continue﻿

warning

多 $ 符号字符串插值(Interpolation)﻿

warning

支持对扩展 API (extend API) 要求使用者同意﻿

note

改进了对带有泛型类型的函数的重载(overload)解析﻿

改进了使用封闭类的 when 表达式的穷尽检查﻿

Kotlin K2 编译器﻿

额外的编译器检查﻿

全局压制警告﻿

K2 kapt 实现的改善﻿

warning

解析无符号类型与非基本类型之间的重载冲突﻿

扩展函数的重载﻿

顶级函数的重载﻿

Kotlin/JVM﻿

JSpecify 可否为 null(Nullability) 不匹配诊断的严重性变更为 strict﻿

Kotlin Multiplatform﻿

跨平台项目中用于编译器选项的新 Gradle DSL 进入稳定版﻿

Kotlin Multiplatform 中的 Gradle 隔离项目(Isolated Project) (预览版)﻿

warning

对 Swift 导出的基本支持﻿

warning

如何启用 Swift 导出﻿

留下对 Swift 导出功能的反馈意见﻿

能够从任何主机发布 Kotlin 库﻿

warning

如何启用从任何主机发布库的功能﻿

对从任何主机发布库的功能留下反馈意见﻿

支持不打包的(non-packed) klib﻿

如何设置你的项目﻿

进一步废弃旧的 android 编译目标﻿

不再支持声明相同类型的多个编译目标﻿

Kotlin/Native﻿

iosArm64 提升为第 1 层﻿

LLVM 从 11.1.0 更新到 16.0.0﻿

对在 cinterop 中缓存的变更﻿

废弃 mimalloc 内存分配器﻿

Kotlin/Wasm﻿

对增量编译的支持﻿

浏览器 APIs 移动到了独立的 kotlinx-browser 库﻿

改善了 Kotlin/Wasm 的调试体验﻿

减少了 Kotlin/Wasm 二进制文件的大小﻿

改善了 Kotlin/Wasm 中的 JavaScript 数组互操作性﻿

在 Kotlin/Wasm 中支持访问 JavaScript 异常的详细信息﻿

废弃默认导出﻿

子项目特定的 Node.js 设置﻿

Kotlin/JS﻿

在属性中支持非标识符字符﻿

支持生成 ES2015 箭头函数(Arrow Function)﻿

Gradle 改善﻿

支持的 AGP 最低版本提升到 7.3.1﻿

支持的 Gradle 最低版本提升到 7.6.3﻿

针对 Kotlin Gradle plugin 扩展的新 API﻿

编译器 符号 hidden from the Kotlin Gradle plugin API﻿

使用 Gradle Workers API﻿

Compose 编译器的更新﻿

支持多个稳定性配置文件﻿

可暂停的组合(Pausable composition)﻿

note

对 open 和可覆盖的(overridden) @Composable 函数的变更﻿

性能改善﻿

标准库﻿

对标准库 API 废弃的严重级别的变更﻿

对 java.nio.file.Path 的文件树遍历扩展函数进入稳定版﻿

文档更新﻿

语言概念﻿

Compose 编译器﻿

API 参考文档﻿

跨平台开发﻿

工具﻿

Kotlin 2.1.0 兼容性指南﻿

安装 Kotlin 2.1.0﻿

IDE 支持

语言

带主语(Subject)的 when 中的保护条件(Guard Condition)

非局部的(non-local) break 和 continue

多 `$` 符号字符串插值(Interpolation)

支持对扩展 API (extend API) 要求使用者同意

改进了对带有泛型类型的函数的重载(overload)解析

改进了使用封闭类的 when 表达式的穷尽检查

Kotlin K2 编译器

额外的编译器检查

全局压制警告

K2 kapt 实现的改善

解析无符号类型与非基本类型之间的重载冲突

扩展函数的重载

顶级函数的重载

Kotlin/JVM

JSpecify 可否为 null(Nullability) 不匹配诊断的严重性变更为 strict

Kotlin Multiplatform

跨平台项目中用于编译器选项的新 Gradle DSL 进入稳定版

Kotlin Multiplatform 中的 Gradle 隔离项目(Isolated Project) (预览版)

对 Swift 导出的基本支持

如何启用 Swift 导出

留下对 Swift 导出功能的反馈意见

能够从任何主机发布 Kotlin 库

如何启用从任何主机发布库的功能

对从任何主机发布库的功能留下反馈意见

支持不打包的(non-packed) klib

如何设置你的项目

进一步废弃旧的 `android` 编译目标

不再支持声明相同类型的多个编译目标

Kotlin/Native

iosArm64 提升为第 1 层

LLVM 从 11.1.0 更新到 16.0.0

对在 cinterop 中缓存的变更

废弃 mimalloc 内存分配器

Kotlin/Wasm

对增量编译的支持

浏览器 APIs 移动到了独立的 kotlinx-browser 库

改善了 Kotlin/Wasm 的调试体验

减少了 Kotlin/Wasm 二进制文件的大小

改善了 Kotlin/Wasm 中的 JavaScript 数组互操作性

在 Kotlin/Wasm 中支持访问 JavaScript 异常的详细信息

废弃默认导出

子项目特定的 Node.js 设置

Kotlin/JS

在属性中支持非标识符字符

支持生成 ES2015 箭头函数(Arrow Function)

Gradle 改善

支持的 AGP 最低版本提升到 7.3.1

支持的 Gradle 最低版本提升到 7.6.3

针对 Kotlin Gradle plugin 扩展的新 API

编译器符号 hidden from the Kotlin Gradle plugin API

使用 Gradle Workers API

Compose 编译器的更新

支持多个稳定性配置文件

可暂停的组合(Pausable composition)

对 open 和可覆盖的(overridden) @Composable 函数的变更

性能改善

标准库

对标准库 API 废弃的严重级别的变更

对 java.nio.file.Path 的文件树遍历扩展函数进入稳定版

文档更新

语言概念

Compose 编译器

API 参考文档

跨平台开发

工具

Kotlin 2.1.0 兼容性指南

安装 Kotlin 2.1.0