从 kapt 迁移到 KSP

Kapt (Kotlin 注解处理工具) 允许您将 Java 注解处理器与 Kotlin 代码一起使用，即使这些处理器不专门支持 Kotlin。这是通过从 Kotlin 文件生成 Java 存根来完成的，然后处理器可以读取这些存根。此存根生成操作非常耗时，对构建速度有显著影响。

KSP (Kotlin Symbol Processing) 是 kapt 的 Kotlin 优先替代方案。KSP 直接分析 Kotlin 代码，速度快 2 倍。它对 Kotlin 语言构造有更好的理解。

在迁移过程中，您可以在项目中同时运行 kapt 和 KSP，并且可以逐个模块、逐个库进行迁移。

以下是迁移步骤的概览

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

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

首先，检查您与 kapt 一起使用的库是否已支持 KSP。许多常用库（包括 Dagger、Glide、Room 和 Moshi）都已支持 KSP，其他库也正在添加支持。

您可以在文档中查看支持的库列表，或参考您正在使用的库的文档和问题跟踪器。

将 KSP 插件添加到您的项目

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

Kotlin

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

Groovy

plugins {
    id 'com.google.devtools.ksp' version '2.0.21-1.0.27' 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，因为它们在同一个 artifact 中提供了注解处理器和 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 具有比 kapt 更准确的 Kotlin 类型信息（例如，关于可空性），这意味着 KSP 处理器可以对类型要求更精确。这可能需要您在源代码中进行一些修复，除了更新您的构建文件。
  • 如果您之前向注解处理器传入了参数，您现在可能需要将这些参数传入 KSP。请注意，参数的格式在 kapt 和 KSP 之间可能有所不同。请参阅 KSP 文档并查阅您正在使用的库的文档以了解更多信息。

移除 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
}

其他资源