注解处理器 (KSP) 实战

源：KSP 官方指南

KSP (Kotlin Symbol Processing) 是 Google 为 Kotlin 量身定制的注解处理工具，旨在取代缓慢的 Kapt。

为什么抛弃 Kapt?

• 速度: Kapt 需要先生成 Java Stubs（桩文件），KSP 直接分析 Kotlin AST。KSP 通常快 2 倍以上。
• 特性: KSP 能完美理解 Kotlin 特性（如 internal、val/var、扩展函数），而 Kapt 只能看到转换后的 Java 签名。

环境配置

KSP 作为一个编译器插件，需要在项目根目录及模块中进行配置：

libs.versions.toml

[plugins]
# 版本需与 Kotlin 版本严格对应，参考：https://github.com/google/ksp/releases
ksp = { id = "com.google.symbolprocessing", version = "1.9.23-1.0.19" }

build.gradle.kts (App)

plugins {
    alias(libs.plugins.ksp)
}

dependencies {
    // 示例：使用 Room 的 KSP 处理器
    ksp(libs.androidx.room.compiler)
}

核心 API

KSP 的 API 设计非常直观：

• Resolver: 解析器，用于查找类、函数。
• KSClassDeclaration: 类定义。
• KSFunctionDeclaration: 函数定义。

class MyProcessor : SymbolProcessor {
    override fun process(resolver: Resolver): List<KSAnnotated> {
        // 查找带有 @MyAnnotation 的符号
        resolver.getSymbolsWithAnnotation("com.example.MyAnnotation")
            .filterIsInstance<KSClassDeclaration>()
            .forEach { clazz ->
                generateCode(clazz)
            }
        return emptyList()
    }
}

实战建议

1. 增量编译: 务必在创建文件时声明 Dependencies，否则修改一行代码会导致全量重新生成。
2. Debug: 可以通过 ./gradlew clean build -Dkotlin.compiler.execution.strategy="in-process" 来调试处理器。