从 kapt 迁移到 KSP

Kapt（Kotlin 注解处理工具） 允许您将 Java 注解处理器与 Kotlin 代码一起使用，即使这些处理器没有专门针对 Kotlin 的支持。这是通过从 Kotlin 文件生成 Java 存根来实现的，然后处理器可以读取这些存根。此存根生成是一个代价高昂的操作，会严重影响构建速度。

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

在迁移过程中，您可以在项目中同时运行 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 "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 后，您可以开始将 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 的功能集支持并不完全相同。如果您的代码在迁移后中断，请检查库的文档。
  • KSP 比 kapt 具有更准确的 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
}

其他资源