Kotlin 1.8.20 版中的新功能

要启用并测试 Kotlin K2 编译器, 请通过下面的编译器选项, 使用新的语言版本:

-language-version 2.0

你可以在你的 build.gradle(.kts) 文件中指定这个选项:

kotlin {
   sourceSets.all {
       languageSettings {
           languageVersion = "2.0"
       }
   }
}

以前的 -Xuse-k2 编译器选项已被废弃.

warning

新 K2 编译器的 Alpha 版只能用于 JVM 和 JS IR 项目. 它还不支持 Kotlin/Native, 也不支持任何 跨平台项目.

如果你能提供你的反馈意见, 我们将会非常感谢!

• 在 Kotlin Slack 频道中, 直接向 K2 开发者提供你的反馈意见 – 获得邀请 并加入 #k2-early-adopters 频道.

• 在 我们的问题追踪系统 中报告你遇到的新 K2 编译器的问题.

• 启用 Send usage statistics 选项, 允许 JetBrains 收集关于 K2 使用状况的匿名数据.

warning

这个功能是 实验性功能. 它随时有可能变更或被删除. 需要使用者同意(Opt-in) (详情见下文). 请注意, 只为评估和试验目的来使用这个功能. 希望你能通过 YouTrack 提供你的反馈意见.

枚举类有一个合成(synthetic)函数 values(), 它返回一个数组, 其中包含枚举类中定义的枚举常数. 但是, 使用数组可能导致 Kotlin 和 Java 中的 隐含的性能问题. 此外, 大多数 API 都使用集合, 因此最终还是需要转换. 为了解决这些问题, 我们为枚举类引入了 entries 属性, 用来替代 values() 函数. 调用时, entries 属性返回一个预先分配的可不变 List, 其中包含枚举类中定义的枚举常数.

tip

values() 函数仍然继续支持, 但我们推荐你改为使用 entries 属性.

enum class Color(val colorName: String, val rgb: String) {
    RED("Red", "#FF0000"),
    ORANGE("Orange", "#FF7F00"),
    YELLOW("Yellow", "#FFFF00")
}

@OptIn(ExperimentalStdlibApi::class)
fun findByRgb(rgb: String): Color? = Color.entries.find { it.rgb == rgb }

tasks
    .withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask<*>>()
    .configureEach {
        compilerOptions
            .languageVersion
            .set(
                org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
            )
    }

tasks
    .withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class)
    .configureEach {
        compilerOptions.languageVersion =
            org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
    }

数据对象(Data Object) 允许你声明 singleton 语义的对象, 并带有一个干净的 toString() 表达. 在下面的代码片段中, 你可以看到向一个对象声明添加 data 关键字, 如何改善它的 toString() 输出的可读性:

package org.example
object MyObject
data object MyDataObject

fun main() {
    println(MyObject) // 输出结果为 org.example.MyObject@1f32e575
    println(MyDataObject) // 输出结果为 MyDataObject
}

特别是对于 sealed 类型层级结构(例如 sealed class 或 sealed interface 类型层级结构), 非常适合使用 data objects, 因为可以与 data class 声明一起方便的使用. 在下面的代码片段中, 将 EndOfFile 声明为 data object 而不是普通的 object, 代表它自动拥有漂亮的 toString, 不需要手动的覆盖这个函数. 这样就保持了与相应的数据类定义的对称性.

sealed interface ReadResult
data class Number(val number: Int) : ReadResult
data class Text(val text: String) : ReadResult
data object EndOfFile : ReadResult

fun main() {
    println(Number(7)) // 输出结果为 Number(number=7)
    println(EndOfFile) // 输出结果为 EndOfFile
}

data object MyDataObject {
    val x: Int = 3
}

fun main() {
    println(MyDataObject) // 输出结果为 MyDataObject
}

import java.lang.reflect.Constructor

data object MySingleton

fun main() {
    val evilTwin = createInstanceViaReflection()

    println(MySingleton) // 输出结果为 MySingleton
    println(evilTwin) // 输出结果为 MySingleton

    // 即使一个库强行创建了 MySingleton 的第二个实例, 它的 `equals` 方法也会返回 true:
    println(MySingleton == evilTwin) // 输出结果为 true

    // 不要使用 === 比较数据对象.
    println(MySingleton === evilTwin) // 输出结果为 false
}

fun createInstanceViaReflection(): MySingleton {
    // Kotlin 的反射功能不允许创建数据对象的实例.
    // 这段代码 "强行" 创建新的 MySingleton 实例 (也就是通过 Java 平台的反射功能)
    // 在你的代码中一定不要这样做!
    return (MySingleton.javaClass.declaredConstructors[0].apply { isAccessible = true } as Constructor<MySingleton>).newInstance()
}

tasks
    .withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask<*>>()
    .configureEach {
        compilerOptions
            .languageVersion
            .set(
                org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
            )
    }

tasks
    .withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class)
    .configureEach {
        compilerOptions.languageVersion =
            org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
    }

warning

这个功能是 实验性功能. 它随时有可能变更或被删除. 需要使用者同意(Opt-in) (详情见下文). 请注意, 只为评估和试验目的来使用这个功能. 希望你能通过 YouTrack 提供你的反馈意见.

Kotlin 1.8.20 解除了在 内联类(Inline class) 中使用有 body 的次级构造器(secondary constructor)的限制.

内联类过去只允许 public 的主构造器, 不允许使用 init 代码块或次级构造器, 以便保证初始化代码的语义清晰. 这就造成, 无法封装底层值, 或创建一个内联类来表达某些受限定的值.

这些问题现在已经解决了. Kotlin 1.4.30 取消了对 init 代码块的限制. 现在我们更进一步, 允许有 body 的次级构造器 (预览版):

@JvmInline
value class Person(private val fullName: String) {
    // 从 Kotlin 1.4.30 开始可以使用:
    init {
        check(fullName.isNotBlank()) {
            "Full name shouldn't be empty"
        }
    }

    // 从 Kotlin 1.8.20 开始可以使用 (预览版):
    constructor(name: String, lastName: String) : this("$name $lastName") {
        check(lastName.isNotBlank()) {
            "Last name shouldn't be empty"
        }
    }
}

tasks
    .withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask<*>>()
    .configureEach {
        compilerOptions
            .languageVersion
            .set(
                org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
            )
    }

tasks
    .withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class)
    .configureEach {
        compilerOptions.languageVersion =
            org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
    }

要启用并测试 Kotlin/Wasm, 请更新你的 build.gradle.kts 文件:

plugins {
    kotlin("multiplatform") version "1.8.20"
}

kotlin {
    wasm {
        binaries.executable()
        browser {
        }
    }
    sourceSets {
        val commonMain by getting
        val commonTest by getting {
            dependencies {
                implementation(kotlin("test"))
            }
        }
        val wasmMain by getting
        val wasmTest by getting
    }
}

tip

请查看 Kotlin/Wasm 示例程序的 GitHub 代码仓库.

要运行 Kotlin/Wasm 项目, 你需要更新目标环境的设定:

如果你能提供你的反馈意见, 我们将会非常感谢!

• 在 Kotlin Slack 频道中, 直接向开发者提供你的反馈意见 – 获得邀请, 并加入 #webassembly 频道.

• 在 这个 YouTrack issue 中, 报告你遇到的 Kotlin/Wasm 的问题.

warning

这个功能是 实验性功能. 它随时有可能变更或被删除. 请注意, 只为评估和试验目的来使用这个功能. 希望你能通过 YouTrack 提供你的反馈意见.

Kotlin 1.8.20 引入了新的功能, 可以创建 Java 合成属性(synthetic property) 引用, 例如, 对这段 Java 代码:

public class Person {
    private String name;
    private int age;

    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }

    public String getName() {
        return name;
    }

    public int getAge() {
        return age;
    }
}

Kotlin 允许你使用 person.age, 其中 age 是一个合成属性. 现在, 你还可以创建 Person::age 和 person::age 的引用. 对 name 也是一样.

val persons = listOf(Person("Jack", 11), Person("Sofie", 12), Person("Peter", 11))
    persons
        // 调用 Java 合成属性的引用:
        .sortedBy(Person::age)
        // 通过 Kotlin 的属性语法, 调用 Java 取值方法:
        .forEach { person -> println(person.name) }

tasks
    .withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask<*>>()
    .configureEach {
        compilerOptions
            .languageVersion
            .set(
                org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
            )
    }

tasks
    .withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class)
    .configureEach {
        compilerOptions.languageVersion =
            org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
}

在 Kotlin 1.7.20 中, 我们引入了 在 kapt stub 生成任务中支持 JVM IR 后端 功能. 从这个发布版开始, 默认启用这个支持. 你不再需要在你的 gradle.properties 中指定 kapt.use.jvm.ir=true 来启用这个功能. 关于这个功能, 希望你能通过 YouTrack 提供你的反馈意见.

Kotlin 开发组决定重新审查 Kotlin/Native 支持的目标平台, 将它们分为不同的支持层级, 并从 Kotlin 1.8.20 开始废弃其中的一部分. 关于支持的和废弃的目标平台的完整列表, 请参见 Kotlin/Native 支持的目标平台.

从 Kotlin 1.8.20 开始, 以下目标平台已被废弃, 将在 1.9.20 中删除:

• iosArm32

• watchosX86

• wasm32

• mingwX86

• linuxArm32Hfp

• linuxMips32

• linuxMipsel32

对于剩下的目标平台, 根据 Kotlin/Native 编译器中支持和测试程度的不同, 现在分为 3 个支持层级. 一个目标平台可能被移动到不同的层级. 例如, 将来我们会尽最大努力对 iosArm64 提供完全的支持, 因为它对 Kotlin Multiplatform 非常重要.

如果你是库的作者, 这 3 个支持层级能够帮助你决定在 CI 工具中测试哪些目标平台, 略过哪些目标平台. Kotlin 开发组在 Kotlin 官方库的开发中也使用这个方案, 例如 kotlinx.coroutines.

关于这些变更的原因, 详情请阅读我们的 blog.

从 1.8.20 开始, 旧的内存管理器已被废弃, 并将在 1.9.20 中删除. 新的内存管理器 已在 1.7.20 中默认启用, 之后还进行了一些稳定性更新和性能改进.

如果你还在使用旧的内存管理器, 请从你的 gradle.properties 文件删除 kotlin.native.binary.memoryModel=strict 选项, 并遵循我们的 迁移指南 进行必要的变更.

新的内存管理器不支持 wasm32 目标平台. 这个目标平台 从这个发布版开始已被废弃, 并将在 1.9.20 中删除.

warning

这个功能是 实验性功能. 它随时有可能变更或被删除. 需要使用者同意(Opt-in) (详情见下文). 请注意, 只为评估和试验目的来使用这个功能. 希望你能通过 YouTrack 提供你的反馈意见.

Kotlin/Native 现在可以导入带 @import 指令的 Objective-C 头文件. 在使用具有自动生成的 Objective-C 头文件的 Swift 库, 或使用 Swift 编写的 CocoaPods 依赖项的类时, 这个功能非常有用.

在以前的版本中, cinterop 工具无法通过 @import 指令分析依赖于 Objective-C 模块的头文件. 因为它缺乏对 -fmodules 选项的支持.

从 Kotlin 1.8.20 开始, 你可以使用带 @import 的 Objective-C 头文件. 为了使用这个功能, 请在定义文件中通过 compilerOpts 向编译器传递 -fmodules 选项. 如果你使用 CocoaPods 集成, 请在 pod() 函数的在配置代码块中指定 cinterop 选项, 如下:

kotlin {
    ios()

    cocoapods {
        summary = "CocoaPods test library"
        homepage = "https://github.com/JetBrains/kotlin"

        ios.deploymentTarget = "13.5"

        pod("PodName") {
            extraOpts = listOf("-compiler-option", "-fmodules")
        }
    }
}

这是一个 期待已久的功能, 我们欢迎你在 YouTrack 中提供你的反馈意见, 帮助我们在未来的发布版中将它变成默认功能.

从 Kotlin 1.8.20 开始, 你可以将 Pod 依赖项和动态框架(dynamic framework)一起使用, 只用于链接, 而不生成 cinterop 绑定. 对于 cinterop 绑定已经生成的情况, 这个功能可能会有用.

考虑一个项目, 有 2 个模块, 1 个是库, 1 个是应用程序. 库依赖于一个 Pod, 但不产生框架, 只产生 1 个 .klib. 应用程序依赖于库, 并产生一个动态框架(dynamic framework). 对于这样的情况, 你需要使用使用库依赖的 Pod 来链接这个框架, 但你不需要 cinterop 绑定, 因为已经为库生成了绑定.

要启用这个功能, 请在添加 Pod 依赖项时使用 linkOnly 选项, 或构建器属性:

cocoapods {
    summary = "CocoaPods test library"
    homepage = "https://github.com/JetBrains/kotlin"

    pod("Alamofire", linkOnly = true) {
        version = "5.7.0"
    }
}

note

如果你对静态框架使用这个选项, 它会删除整个 Pod 依赖项, 因为对静态框架的链接不会使用 Pod.

从 Xcode 14.1 开始, 来自 Objective-C 类的一些方法已经被移动为类别成员(category member). 这会导致生成不同的 Kotlin API, 而且这些方法会被导入为 Kotlin 扩展, 而不是方法.

在使用 UIKit 并覆盖方法时, 你可能已经遇到了这个变更造成的问题. 例如, 在 Kotlin 中继承 UIVIew 类时, 将会无法覆盖 drawRect() 或 layoutSubviews() 方法.

从 1.8.20 开始, 在与 NSView 和 UIView 类相同的头文件中声明的类别成员(category member), 会被导入为这些类的成员. 因此, 从 NSView 和 UIView 继承的子类, 可以很容易的覆盖这些方法, 就像其它方法一样.

如果一切顺利, 我们计划对所有的 Objective-C 类默认启用这个行为.

为了加快编译器缓存功能的演进速度, 我们将编译器缓存管理从 Kotlin Gradle plugin 移动到了 Kotlin/Native 编译器中. 这样做就使得我们可以进行几项重要的改进工作, 包括编译速度和编译器缓存灵活性相关的改进.

如果你遇到问题, 需要回到原来的行为, 请使用 Gradle 属性 kotlin.native.cacheOrchestration=gradle.

希望你能通过 YouTrack 提供你的反馈意见.

Kotlin 1.8.20 开始了 useLibraries() 函数的废弃周期, 这个函数用于静态库的 CocoaPods 集成.

我们过去引入 useLibraries() 函数, 是为了允许使用包含静态库的 Pod 依赖项. 随着时间的推移, 这样的情况变得非常罕见. 大多数 Pod 都使用源代码来发布, 而且二进制的发布通常会选择 Objective-C 框架或 XCFramework.

由于不再需要使用这个函数, 而且它会导致一些问题, 使得 Kotlin CocoaPods Gradle plugin 的开发变得复杂, 我们决定废弃它.

关于框架和 XCFramework, 更多详情请参见 构建最终的原生二进制文件.

warning

源代码集层级结构的新方案是 实验性功能. 在未来的 Kotlin 发布版中, 它随时有可能变更, 不会预先通知. 需要使用者同意(Opt-in) (详情见下文). 希望你能通过 YouTrack 提供你的反馈意见.

Kotlin 1.8.20 提供了一种新的方式, 在你的跨平台项目中设置源代码集层级结构 − 默认的编译目标层级结构. 新方案旨在替代编译目标的简写(shortcut), 例如 ios, 这些编译目标简写(shortcut)存在 设计缺陷.

默认的编译目标层级结构背后的理念非常简单: 你要明确声明你的项目所有编译目标, Kotlin Gradle plugin 会根据指定的编译目标自动创建共用的源代码集.

设置你的项目

以下面这个简单的跨平台移动应用程序为例子:

@OptIn(ExperimentalKotlinGradlePluginApi::class)
kotlin {
    // 启用默认的编译目标层级结构:
    targetHierarchy.default()

    android()
    iosArm64()
    iosSimulatorArm64()
}

你可以将默认的编译目标层级结构看作一个模板, 其中包含所有可能的编译目标以及它们的共用源代码集. 当你在你的代码中声明最终的编译目标 android, iosArm64, 和 iosSimulatorArm64 时, Kotlin Gradle plugin 会从模板中找到合适的共用源代码集, 并为你创建这些共用源代码集. 最终产生的层级结构如下:

绿色的源代码集会自动创建并包含到项目中, 同时, 默认模板中的灰色的源代码集会被忽略. 你可以看到, Kotlin Gradle plugin 没有创建一些源代码集, 例如 watchos, 因为项目中没有 watchOS 编译目标.

如果你添加一个 watchOS 编译目标, 例如 watchosArm64, watchos 源代码集就会被创建, 来自 apple, native, 和 common 源代码集的代码也会被编译到 watchosArm64.

关于默认的编译目标层级结构的完整构成, 请参见 文档.

note

在这个示例中, apple 和 native 源代码集只会对 iosArm64 和 iosSimulatorArm64 编译目标编译. 因此, 尽管它们的名字不是 ios, 它们可以访问完整的 iOS API. 对于 native 这样的源代码集, 这可能会违反直觉, 因为你可能会期望在这个源代码集中, 只能访问那些所有原生编译目标都能够使用的 API. 这个行为未来可能会变更.

note

从 Kotlin Gradle Plugin 1.8.20 开始, 在 Gradle 构建中支持这个功能. 对于 IDE 支持, 请使用 IntelliJ IDEA 2023.1 Beta 2 (231.8109.2) 或更高版本, 以及 Kotlin Gradle plugin 1.8.20, 与任何版本的 Kotlin IDE plugin 一起使用.

从 1.8.20 开始, Kotlin Multiplatform 支持 Gradle 复合构建(composite build). 复合构建允许你将其他项目的构建, 或同一项目的其它部分的构建, 包含到单个构建中.

由于一些技术困难, 对 Kotlin Multiplatform 使用 Gradle 符合构建还只有部分的支持. Kotlin 1.8.20 包含了对复合构建支持的改进(预览版), 应该能够适用于更多种类的项目. 要试用这个功能, 请向你的 gradle.properties 添加以下选项:

kotlin.mpp.import.enableKgpDependencyResolution=true

这个选项会启用新的导入模式的预览版. 除了支持复合构建, 它还提供了跨平台项目中更流畅的导入体验, 因为我们包含了一些重大的 Bug 修复和改进, 使得导入功能更加稳定.

如果在 Xcode 中构建你的跨平台项目时遇到问题, 你可能看到 "Command PhaseScriptExecution failed with a nonzero exit code" 错误信息. 这个错误信息表示 Gradle 调用失败了, 但要调查问题的原因, 这个错误信息就没什么帮助.

从 Kotlin 1.8.20 开始, Xcode 能够解析 Kotlin/Native 编译器的输出. 而且, 对于 Gradle 构建失败的情况, 你会在 Xcode 中看到来自根本原因异常的附加错误信息. 大多数情况下, 这些信息能够帮助你找到根本问题.

对用于 Xcode 集成的标准 Gradle task, 这个新行为默认启用, 例如 embedAndSignAppleFrameworkForXcode, 它能够将 iOS 框架从你的跨平台应用程序连接到 Xcode 中的 iOS 应用程序. 也可以使用 kotlin.native.useXcodeMessageStyle Gradle 属性来启用 (或关闭).

在 Kotlin 1.8.20 中, 我们从 Kotlin/JavaScript Gradle plugin 中删除了 实验性的 Dukat 集成功能. Dukat 集成功能支持从 TypeScript 声明文件 (.d.ts) 到 Kotlin 外部声明的自动转换.

你仍然可以使用我们的 Dukat 工具, 将 TypeScript 声明文件 (.d.ts) 转换为 Kotlin 外部声明.

warning

Dukat 工具是 实验性功能. 它随时有可能变更或被删除.

为了帮助调试, 我们引入了一种功能, 能够向你的代码映射(Source Map)添加你在 Kotlin 代码中声明的变量和函数的名称. 在 1.8.20 之前, 这些名称在代码映射(Source Map)中是不可用的, 因此在调试器中, 你看到的是生成的 JavaScript 的变量和函数名称.

你可以在你的 Gradle 文件 build.gradle.kts 中使用 sourceMapNamesPolicy 来配置添加哪些名称, 也可以使用编译器选项 -source-map-names-policy. 下表是可用的设置:

下面是在 build.gradle.kts 文件中配置的示例:

tasks.withType<org.jetbrains.kotlin.gradle.tasks.Kotlin2JsCompile>().configureEach {
    compilercompileOptions.sourceMapNamesPolicy.set(org.jetbrains.kotlin.gradle.dsl.JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES) // 或 SOURCE_MAP_NAMES_POLICY_NO, or SOURCE_MAP_NAMES_POLICY_SIMPLE_NAMES
}

调试工具, 例如基于 Chromium 的浏览器中提供的调试工具, 能够从你的代码映射中获取原始的 Kotlin 名称, 改进你的调用栈的可读性. 祝你调试快乐!

warning

在代码映射中添加变量和函数名称是 实验性功能. 它随时有可能变更或被删除.

以前, 如果你的项目生成可执行的文件 (binaries.executable()), Kotlin/JS IR 编译器会收集所有标注了 @JsExport 的顶级声明, 并自动在一个 .d.ts 文件中生成 TypeScript 定义.

由于这个功能并不是对每个项目都有用, 在 Kotlin 1.8.20 中我们修改了这个行为. 如果你想要生成 TypeScript 定义, 你需要在你的 Gradle 构建文件中明确的配置. 向你的 build.gradle.kts.file 文件的 js 小节 添加 generateTypeScriptDefinitions(). 例如:

kotlin {
    js {
        binaries.executable()
        browser {
        }
        generateTypeScriptDefinitions()
    }
}

warning

TypeScript 定义 (d.ts) 的生成是 实验性功能. 它随时有可能变更或被删除.

Gradle 提供了一种方式, 保证那些需要一起工作的依赖项能够 对齐它们的版本. Kotlin 1.8.20 也采用了这个方案. 这个功能默认启用, 因此你不需要修改或更新你的配置来启用它. 此外, 你不再需要 使用这个变通方法来解析 Kotlin Gradle plugin 的传递依赖项.

希望你能通过 YouTrack 提供你的反馈意见.

增量编译的新方案, 从 Kotlin 1.7.0 开始可以使用, 现在变为默认使用. 你不再需要在你的 gradle.properties 中指定 kotlin.incremental.useClasspathSnapshot=true 来启用它.

希望你能提供你的反馈意见. 你可以在 YouTrack 中 提交一个 issue.

warning

对编译任务的输出的精确备份是 实验性功能. 要使用这个功能, 请向 gradle.properties 添加 kotlin.compiler.preciseCompilationResultsBackup=true. 希望你能通过 YouTrack 提供你的反馈意见.

从 Kotlin 1.8.20 开始, 你可以启用精确备份, 这时只有 Kotlin 在 增量编译 中重新编译的那些类会被备份. 完整备份和精确备份都可以帮助在发生编译错误后再次运行增量构建. 精确备份与完整备份相比, 会耗费较少的构建时间. 对于大型的项目, 或者很多任务都创建备份, 那么完整备份可能会花费 明显 更长的构建时间, 尤其是如果项目位于速度较慢的 HDD 上.

这个优化是实验性功能. 要启用这个功能, 请向 gradle.properties 文件添加 kotlin.compiler.preciseCompilationResultsBackup Gradle 属性:

kotlin.compiler.preciseCompilationResultsBackup=true

JetBrains 使用精确备份的例子

在下面的图表中, 你可以看到使用精确备份与完整备份相对比的示例:

第一个和第二个对比图显示了在 Kotlin 项目中使用精确备份时对 Kotlin Gradle plugin 构建的影响:

1. 进行一个小的 ABI 变更之后: 向一个被大量模块依赖的模块添加一个新的 public 方法.

2. 进行一个小的非 ABI 变更之后: 向一个没有被其他模块依赖的模块添加一个 private 函数.

第三个对比图显示了在 Space 项目中使用精确备份时, 在小的非 ABI 更改后对 Web 前端构建的影响: 向一个被大量模块依赖的 Kotlin/JS 模块添加一个 private 函数.

我们在使用 Apple M1 Max CPU 的计算机上进行这些测量; 在不同的计算机上会出现稍微不同的结果. 影响性能的因素包括但不限于以下几点:

• Kotlin daemon 和 Gradle daemon 热身状况(warm)如何..

• 硬盘速度如何.

• CPU 型号, 以及它的繁忙程度.

• 哪些模块受到变更的影响, 以及这些模块有多大.

• 是 ABI 变更还是非 ABI 变更.

kotlin.build.report.output=file

Task ':kotlin-gradle-plugin:compileCommonKotlin' finished in 0.59 s
<...>
Time metrics:
 Total Gradle task time: 0.59 s
 Task action before worker execution: 0.24 s
  Backup output: 0.22 s // 注意这个数字
<...>

Task ':kotlin-gradle-plugin:compileCommonKotlin' finished in 0.46 s
<...>
Time metrics:
 Total Gradle task time: 0.46 s
 Task action before worker execution: 0.07 s
  Backup output: 0.05 s // 备份消耗的时间减少了
 Run compilation in Gradle worker: 0.32 s
  Clear jar cache: 0.00 s
  Precise backup output: 0.00 s // 与精确备份相关的输出
  Cleaning up the backup stash: 0.00 s // 与精确备份相关的输出
<...>

对于在 Gradle 7.3+ 中使用了 org.jetbrains.kotlin.gradle.jvm plugin 的项目, Kotlin Gradle plugin 不会过早的创建和配置 compileKotlin 任务. 在更低版本的 Gradle 中, 它只是简单的注册所有任务, 不会在空运行(dry run)阶段配置任务. 在使用 Gradle 7.3+ 时, 现在也会是相同的行为.

如果你有下面的设置, 那么请更新你的构建脚本, 添加一些新的设置:

• 覆盖了 Kotlin/JVM KotlinJvmCompile/KotlinCompile 任务的 destinationDirectory 位置.

• 使用了废弃的 Kotlin/JS/非 IR 变体(variant), 并覆盖了 Kotlin2JsCompile 任务的 destinationDirectory.

在你的 JAR 文件中, 除 sourceSets.main.outputs 之外, 你需要明确的添加 sourceSets.main.kotlin.classesDirectories:

tasks.jar(type: Jar) {
    from sourceSets.main.outputs
    from sourceSets.main.kotlin.classesDirectories
}

现在你可以控制 Kotlin Gradle plugin 是否应该在 HTTP 构建报告 中包含编译器参数. 有些时候, 你可能不需要让 plugin 报告这些参数. 如果一个项目包含很多模块, 它在报告中的的编译器参数 可能非常多, 而且没什么用处. 现在有一种方法能够关闭这个信息, 并节省内存. 请在你的 gradle.properties 或 local.properties 文件中, 使用 kotlin.build.report.include_compiler_arguments=(true|false) 属性.

希望你能通过 YouTrack 提供你的反馈意见.

warning

新的 AutoCloseable 接口是 实验性功能, 要使用它, 你需要通过 @OptIn(ExperimentalStdlibApi::class) 标注使用者同意(Opt-in), 或通过编译器参数 -opt-in=kotlin.ExperimentalStdlibApi.

AutoCloseable 接口已经添加到了共通的标准库, 因此你可以对所有的库使用共通的接口来关闭资源. 在 Kotlin/JVM 中, AutoCloseable 接口是 java.lang.AutoClosable 的别名(alias).

此外, 还包含了扩展函数 use(), 它会对一个指定的资源执行一个给定的函数块, 然后正确的关闭这个资源, 无论函数块执行过程中是否抛出了异常.

在共通的标准库中没有实现 AutoCloseable 接口的 public 类. 在下面的示例中, 我们定义了一个 XMLWriter 接口, 假设有一个资源实现了这个接口. 例如, 这个资源可以是一个类, 它打开文件, 写入 XML 内容, 然后关闭文件.

interface XMLWriter : AutoCloseable {
    fun document(encoding: String, version: String, content: XMLWriter.() -> Unit)
    fun element(name: String, content: XMLWriter.() -> Unit)
    fun attribute(name: String, value: String)
    fun text(value: String)
}

fun writeBooksTo(writer: XMLWriter) {
    writer.use { xml ->
        xml.document(encoding = "UTF-8", version = "1.0") {
            element("bookstore") {
                element("book") {
                    attribute("category", "fiction")
                    element("title") { text("Harry Potter and the Prisoner of Azkaban") }
                    element("author") { text("J. K. Rowling") }
                    element("year") { text("1999") }
                    element("price") { text("29.99") }
                }
                element("book") {
                    attribute("category", "programming")
                    element("title") { text("Kotlin in Action") }
                    element("author") { text("Dmitry Jemerov") }
                    element("author") { text("Svetlana Isakova") }
                    element("year") { text("2017") }
                    element("price") { text("25.19") }
                }
            }
        }
    }
}

warning

新的编码和解码功能是 实验性功能, 要使用它, 你需要通过 @OptIn(ExperimentalEncodingApi::class) 标注使用者同意(Opt-in), 或通过编译器参数 -opt-in=kotlin.io.encoding.ExperimentalEncodingApi.

我们添加了 Base64 编码和解码的支持. 我们提供了 3 个类实例, 每个使用不同的编码方案, 并表现出不同的行为. 对于标准的 Base64 编码方案, 请使用 Base64.Default 实例.

对于 "URL 和文件名安全的" 编码方案, 请使用 Base64.UrlSafe 实例.

对于 MIME 编码方案, 请使用 Base64.Mime 实例. 如果你使用 Base64.Mime 实例, 所有的编码函数会对每 76 个字符插入 1 个行分隔符. 对于解码的情况, 所有的非法字符会被跳过, 不抛出异常.

tip

Base64.Default 实例 Base64 类的是伴随对象. 因此, 你可以通过 Base64.encode() 和 Base64.decode() 的方式调用它的函数, 而不必写为 Base64.Default.encode() 和 Base64.Default.decode().

val foBytes = "fo".map { it.code.toByte() }.toByteArray()
Base64.Default.encode(foBytes) // 结果为 "Zm8="
// 也可以写为:
// Base64.encode(foBytes)

val foobarBytes = "foobar".map { it.code.toByte() }.toByteArray()
Base64.UrlSafe.encode(foobarBytes) // 结果为 "Zm9vYmFy"

Base64.Default.decode("Zm8=") // 结果等于 foBytes
// 也可以写为:
// Base64.decode("Zm8=")

Base64.UrlSafe.decode("Zm9vYmFy") // 结果等于 foobarBytes

你可以使用其它函数编码或解码字节, 结果输出到已经存在的缓冲区, 或者将结果添加到指定的 Appendable 类型对象.

在 Kotlin/JVM 中, 我们还添加了扩展函数 encodingWith() 和 decodingWith(), 可以对输入和输出流执行 Base64 编码和解码操作.

warning

Kotlin/Native 中的 @Volatile 是 实验性功能. 它随时有可能变更或被删除. 需要使用者同意(Opt-in) (详情见下文). 请注意, 只为评估和试验目的来使用这个功能. 希望你能通过 YouTrack 提供你的反馈意见.

如果你使用 @Volatile 注解标注一个 var 属性, 那么它的后端域变量(Backing Field) 会被标注这个注解, 使得对这个域变量的所有读写操作都是原子化的, 而且写入操作永远对其它线程可见.

在 1.8.20 之前, kotlin.jvm.Volatile 注解 存在于在共通标准库中. 但是, 这个注解只对 JVM 有效. 如果你在 Kotlin/Native 中使用它, 它会被忽略, 因此导致错误.

在 1.8.20 中, 我们引入了一个共通的注解, kotlin.concurrent.Volatile, 你可以在 JVM 和 Kotlin/Native 中使用.

tasks
    .withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask<*>>()
    .configureEach {
        compilerOptions
            .languageVersion
            .set(
                org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
            )
    }

tasks
    .withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class)
    .configureEach {
        compilerOptions.languageVersion =
            org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
    }

以前 Kotlin 的版本中, 如果你的正规表达式的输入包含了大量的字符, 可能会发生崩溃, 即使正规表达式模式本身非常简单. 在 1.8.20 中, 已经解决了这个问题. 更多详情, 请参见 KT-46211.

warning

对 K2 的序列化编译器 plugin 支持处于 Alpha 阶段. 要使用它, 请 启用 Kotlin K2 编译器.

从 1.8.20 开始, 序列化编译器 plugin 可以与 Kotlin K2 编译器一起使用. 请试用它, 并 向我们提供你的反馈意见!

目前, 可以使用 @Serializable 注解将一个类声明为可序列化, 同时还可以在它的伴随对象上, 使用 @Serializer 注解声明一个自定义的序列化器.

例如:

import kotlinx.serialization.*

@Serializable
class Foo(val a: Int) {
    @Serializer(Foo::class)
    companion object {
        // KSerializer<Foo> 的自定义实现
    }
}

这种情况下, 从 @Serializable 注解无法看出使用了哪个序列化器. 实际上, Foo 类存在一个自定义的序列化器.

为了防止这种混乱, 在 Kotlin 1.8.20 中, 在检测到这种情况时, 我们引入了一个编译器警告. 警告信息中包含一个可能的迁移方案来解决这个问题.

如果你在你的代码中使用了这样的结构, 我们建议修改如下:

import kotlinx.serialization.*

@Serializable(Foo.Companion::class)
class Foo(val a: Int) {
    // 无论是是否标注 @Serializer(Foo::class), 都会起作用
    companion object: KSerializer<Foo> {
        // KSerializer<Foo> 的自定义实现
    }
}

如果这个方案, 可以很清楚的看到, Foo 类使用了伴随对象中声明的自定义的序列化器. 更多详情, 请参见我们的 YouTrack ticket.

tip

在 Kotlin 2.0 中, 我们计划将编译警告升级为编译错误. 如果你看到这个警告, 我们建议你迁移你的代码.

IntelliJ IDEA 2022.2 和 2022.3 会自动建议将 Kotlin plugin 更新到 1.8.20. IntelliJ IDEA 2023.1 会包含 Kotlin plugin 1.8.20.

Android Studio Flamingo (222) 和 Giraffe (223) 会在后续的发布版中支持 Kotlin 1.8.20.

新的命令行编译器可以通过 GitHub 发布页面 下载.

要正确下载 Kotlin 的 artifact 和依赖项, 请更新你的 settings.gradle(.kts) 文件, 使用 Maven Central 仓库:

pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}

如果没有指定仓库, Gradle 会使用已废弃的 JCenter 仓库, 导致无法下载 Kotlin artifact 的错误.