从 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。许多热门库(包括 DaggerGlideRoomMoshi)都属于这种情况,其他库也在增加支持。

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

将 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 语法:

apply plugin: 'kotlin-kapt'

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

Kotlin


kapt {
    correctErrorTypes = true
    useBuildCache = true
}

Groovy


kapt {
    correctErrorTypes true
    useBuildCache true
}

其他资源