注解处理器 (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 版本严格对应
# Kotlin 2.x 推荐使用 KSP2 (Beta) 以获得最佳性能
ksp = { id = "com.google.symbolprocessing", version = "2.0.0-1.0.21" }

build.gradle.kts (App)

plugins {
    alias(libs.plugins.ksp)
}

KSP2 与 K2 编译器 Beta

KSP2 是 KSP 的全新版本，专门为 Kotlin 2.0 (K2) 编译器架构设计。

• 性能飞跃: 在大型项目中，KSP2 的分析速度比 KSP1 快数倍。
• 原生 K2 支持: 能够更准确地处理 K2 编译器的类型系统和解析逻辑。

核心 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" 来调试处理器。