Skip to content

Kotlin Symbol Processing API ​

Kotlin Symbol Processing (KSP) 是适用于 Kotlin 的源代码生成框架。借助 KSP API,你可以创建用于检查源代码静态信息并据此生成新代码的处理器。最常见的用例是基于注解生成代码。

KSP 旨在简化轻量级编译器插件的创建。使用 KSP 构建的编译器插件称为符号处理器,简称处理器。KSP 定义良好的 API 隐藏了编译器的变更,因此你无需花费太多精力来维护处理器。然而,这种做法也伴随着权衡。例如,基于 KSP 的处理器无法检查表达式或语句,也无法修改源代码。

基于 KSP 的插件的典型用例包括:

要了解如何创建你的第一个基于 KSP 的处理器,请参阅 KSP 入门指南。

要求 ​

最新版本的 KSP(2.3.12)支持以下依赖项版本:

依赖项最低与最高版本
Kotlin Gradle plugin (KGP)2.3.20–2.4.x
Android Gradle Plugin (AGP)8.13.0 或更高版本
Gradle8.13 或更高版本。对于 AGP 9.0 或更高版本,请使用 Gradle 9.x。
JDK17 或更高版本

KSP 在编译期间的工作原理 ​

KSP 基于 Kotlin 语法将 Kotlin 源代码表示为符号的层次结构。处理器使用这些符号来检查声明,例如类、函数、属性和类型。

KSP 对声明和类型信息进行建模,但不允许处理器访问表达式或函数体。

KSP 融入编译过程的方式如下:

  1. KSP 处理器分析源代码和资源。

  2. 处理器生成源文件或其他输出。

  3. Kotlin 编译器将原始源代码与生成的代码一起编译。

要详细了解 KSP,请观看此视频:

KSP 如何运行处理器 ​

KSP 使用 SymbolProcessorProvider 的实现作为创建 SymbolProcessor 实例的入口点:

kotlin
interface SymbolProcessorProvider {
    fun create(environment: SymbolProcessorEnvironment): SymbolProcessor
}

SymbolProcessor 接口包含处理逻辑。KSP 调用 process() 函数并提供一个 Resolver,处理器使用它来访问源代码中的符号:

kotlin
interface SymbolProcessor {
    fun process(resolver: Resolver): List<KSAnnotated>
    fun finish() {}
    fun onError() {}
}

有关如何实现和注册处理器的分步指南,请参阅 KSP 入门指南。

支持的库 ​

此表格列出了 Android 上的常用库及其对 KSP 的各个支持阶段:

库状态
Room官方支持
Moshi官方支持
RxHttp官方支持
Kotshi官方支持
Lyricist官方支持
Lich SavedState官方支持
gRPC Dekorator官方支持
EasyAdapter官方支持
Koin Annotations官方支持
Glide官方支持
Micronaut官方支持
Epoxy官方支持
Paris官方支持
Auto Dagger官方支持
SealedX官方支持
Ktorfit官方支持
Mockative官方支持
Kotest官方支持
DeeplinkDispatch通过 airbnb/DeepLinkDispatch#323 支持
DaggerAlpha
MotifAlpha
Hilt进行中
Auto Factory尚不支持

其他资源 ​