从 kapt 迁移到 KSP

Kapt（Kotlin 注释处理工具） 允许您将 Java 注释处理器与 Kotlin 代码一起使用，即使这些处理器没有对 Kotlin 的特定支持。这是通过从您的 Kotlin 文件生成 Java 存根来完成的，然后处理器可以读取这些存根。这种存根生成是一个昂贵的操作，对构建速度有重大影响。

KSP（Kotlin 符号处理） 是 kapt 的 Kotlin优先替代方案。KSP 直接分析 Kotlin 代码，速度可 提升 2 倍。它还对 Kotlin 的语言结构有更好的理解。

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

您可以在迁移过程中将 kapt 和 KSP 并排运行，并且可以逐个模块、逐个库地进行迁移。

以下是迁移步骤的概述

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

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

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

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

将 KSP 插件添加到您的项目

首先，在您的顶级 build.gradle.kts 文件中声明 KSP 插件。确保您选择的 KSP 版本与项目的 Kotlin 版本一致。您可以在 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 后，您可以开始将 kapt 的使用替换为 KSP。对于绝大多数库来说，这只需要将依赖项声明中的 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 中不支持完全相同的特性集。如果您的代码在迁移后出现问题，请检查库的文档。
  • 与 kapt 相比，KSP 提供了更准确的 Kotlin 类型信息（例如，关于可空性），这意味着 KSP 处理器可以更精确地确定类型需求。除了更新构建文件之外，这可能还需要您对源代码进行一些修复。
  • 如果您之前将参数传递给注释处理器，现在可能需要将这些参数传递给 KSP。请注意，参数的格式在 kapt 和 KSP 之间可能有所不同。有关详细信息，请参阅KSP 文档并查阅您使用的库的文档。

删除 kapt 插件

当您的模块不再包含使用kapt的依赖项时，请移除 kapt 插件。

如果它是在 plugins 块中声明的

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
}

其他资源