从 kapt 迁移到 KSP

借助 kapt（Kotlin 注解处理工具），您可以将 Java 注解处理器与 Kotlin 代码搭配使用，即使这些处理器没有特定的 Kotlin 支持也是如此。方法是从 Kotlin 文件生成 Java 桩，然后处理器就可以读取这些桩。生成桩是一项成本高昂的操作，并且对构建速度有很大影响。

KSP (Kotlin Symbol Processing)是以 Kotlin 优先的 kapt 替代方案。KSP 可直接分析 Kotlin 代码，使得速度提高多达 2 倍。此外，它还可以更好地了解 Kotlin 的语言结构。

kapt 目前处于维护模式，因此我们建议您尽可能从 kapt 迁移到 KSP。在大多数情况下，迁移只需更改项目的 build 配置。

在迁移期间，您可以在项目中同时运行 kapt 和 KSP，并且您可以逐个模块、逐个库完成迁移。

下面简要介绍了迁移步骤：

  1. 检查您使用的库是否已支持 KSP
  2. 将 KSP 插件添加到您的项目中
  3. 将注释处理器替换为 KSP
  4. 移除 kapt 插件

检查您使用的库是否已支持 KSP

首先，检查与 kapt 搭配使用的库是否已支持 KSP。许多热门库（包括 Dagger、Glide、Room、 和 Moshi）以及其他人也在不断添加支持。

您可以查看文档中的支持的库列表，或者参阅您所用库的文档和问题跟踪器。

将 KSP 插件添加到您的项目中

首先，在顶级 build.gradle.kts 文件中声明 KSP 插件。 请务必选择与项目的 Kotlin 版本一致的 KSP 版本。您可以在 KSP GitHub 页面上找到版本列表。

Kotlin

plugins {
    id("com.google.devtools.ksp") version "1.8.10-1.0.9" apply false
}

Groovy

plugins {
    id 'com.google.devtools.ksp' version '1.8.10-1.0.9' apply false
}

然后，在模块级 build.gradle.kts 文件中启用 KSP：

Kotlin

plugins {
    id("com.google.devtools.ksp")
}

Groovy

plugins {
    id 'com.google.devtools.ksp'
}

将注释处理器替换为 KSP

启用 KSP 后，您就可以开始用 KSP 替换 kapt 了。对于大部分库，这只需要在依赖项声明中将 kapt 更改为 KSP，因为它们在相同的工件中提供注解处理器和 KSP 处理器。

Kotlin

dependencies {
    kapt("androidx.room:room-compiler:2.5.0")
    ksp("androidx.room:room-compiler:2.5.0")
}

Groovy

dependencies {
    kapt 'androidx.room:room-compiler:2.5.0'
    ksp 'androidx.room:room-compiler:2.5.0'
}

迁移到 KSP 后，请同步并构建您的项目，看看它是否仍可正常运行。

需要注意以下常见问题：

  • 有些库不支持针对 kapt 和 KSP 使用完全相同的功能集。如果您的代码在迁移后出现异常，请参阅相应库的文档。
  • KSP 的 Kotlin 类型信息比 kapt 更准确（例如有关是否可为 null 的信息），这意味着 KSP 处理器对于类型要求更为精确。因此，除了更新 build 文件之外，您可能还需要对源代码进行一些修复。
  • 如果您之前将参数传递给注解处理器，您现在可能需要将这些参数传递给 KSP。请注意，kapt 和 KSP 的参数格式可能有所不同。如需了解详情，请参阅 KSP 文档并查阅所用库的文档。

移除 kapt 插件

如果您的模块中的依赖项不再包含 kapt，请移除 kapt 插件。

如果已在插件块中声明 kapt：

Kotlin

plugins {
    id("org.jetbrains.kotlin.kapt")
}

Groovy

plugins {
    id 'org.jetbrains.kotlin.kapt'
}

如果通过 Groovy 使用“应用插件”语法：

apply plugin: 'kotlin-kapt'

您还应移除与 kapt 相关的所有剩余配置，例如：

Kotlin

kapt {
    correctErrorTypes = true
    useBuildCache = true
}

Groovy

kapt {
    correctErrorTypes true
    useBuildCache true
}

其他资源