从 kapt 迁移到 KSP
本指南介绍如何将注解处理器从 Kotlin 注解处理工具 (kapt) 迁移到 Kotlin Symbol Processing (KSP)。迁移后,你的项目可以充分利用 Kotlin 的语言功能并提升构建性能。
kapt 允许你在 Kotlin 中使用 Java 注解处理器。它会将 Kotlin 源代码转换为 Java“存根 (stub)”,然后在这些存根上运行注解处理器。但是,该过程开销很大,会显著增加构建时间,并且在转换过程中会丢失某些 Kotlin 特有的功能。
相比之下,KSP 是专为 Kotlin 设计的 kapt 替代方案。KSP 通过直接分析 Kotlin 源代码并公开诸如为 null 性 (nullability) 等特定于 Kotlin 的信息,从而减少构建时间。
开始之前
检查项目中的处理器是否支持 KSP。请参阅支持的库列表或查阅其相关文档。
KSP 与 kapt 可以并行运行,因此你可以分阶段迁移项目,一次迁移一个库或模块。
将 KSP 插件添加到你的项目
在项目级 build.gradle(.kts) 文件的 plugins {} 块中添加 KSP 插件:
// build.gradle.kts
plugins {
id("com.google.devtools.ksp") version "2.3.12" apply false
}// build.gradle
plugins {
id 'com.google.devtools.ksp' version '2.3.12' apply false
}要查找 KSP 的最新版本,请查看 GitHub Releases。
在模块中将 kapt 替换为 KSP
找到使用了所需迁移处理器的模块。在该模块的 build.gradle(.kts) 文件中:
将 KSP 插件添加到
plugins {}块中:kotlin// build.gradle.kts plugins { id("com.google.devtools.ksp") }groovy// build.gradle plugins { id 'com.google.devtools.ksp' }在
dependencies {}块中,将kapt替换为ksp:kotlin// build.gradle.kts dependencies { implementation("com.google.dagger:dagger:2.48") // 替换 kapt("com.google.dagger:dagger-compiler:2.48") ksp("com.google.dagger:dagger-compiler:2.48") }groovy// build.gradle dependencies { implementation 'com.google.dagger:dagger:2.48' // 替换 kapt 'com.google.dagger:dagger-compiler:2.48' ksp 'com.google.dagger:dagger-compiler:2.48' }
对于大多数库来说,仅做此替换就足够了。请查看各库的文档,以确认是否需要进行任何其他更改。
移除 kapt 插件
将所有处理器迁移到 KSP 后,你便可以安全地从所有 build.gradle(.kts) 文件中移除 kapt 插件:
// build.gradle.kts
plugins {
// 移除 kapt 插件声明:
id("org.jetbrains.kotlin.kapt")
}// build.gradle
plugins {
// 移除 kapt 插件声明:
id 'org.jetbrains.kotlin.kapt'
}删除任何遗留的 kapt 配置,例如 kapt {} 块(如果存在)。
另请参阅
- 了解如何使用 KSP API 创建自己的处理器。
- 在 Java 注解处理到 KSP 参考指南中查找与 Java 注解处理 API 等效的 KSP API。
- 在 Kotlin Symbol Processing API 概述中了解 KSP 在编译期间的工作原理。
- 探索 KSP 仓库中的示例项目。
