Kotlin 编译器插件：KSP 与编译器前端扩展机制深度

interface SymbolProcessor {
    // 处理函数：在所有符号解析完成后调用
    // resolver.getSymbolsWithAnnotation() 返回的符号在这里处理
    fun process(resolver: Resolver): List<KSNode>

    // finish：在编译结束时调用，用于生成文件
    fun finish()

    // onError：处理过程中遇到错误时调用
    fun onError(error: KSError)
}

// 创建处理器
class MyProcessor : SymbolProcessor {
    override fun process(resolver: Resolver): List<KSNode> {
        // 获取所有标记了 @MyAnnotation 的符号
        val symbols = resolver.getSymbolsWithAnnotation("com.example.MyAnnotation")
        symbols.filter { it is KSClassDeclaration }
            .forEach { processClass(it) }
        return emptyList()
    }
}

// Resolver 提供的查询方法
// 1. 按注解查询
Resolvers.getSymbolsWithAnnotation("com.example.MyAnnotation")

// 2. 按包名查询所有类
Resolver.getClassDeclarationsInPackage("com.example")

// 3. 查找类型引用
Resolver.getTypeArguments(typeRef: KSTypeReference)

// 4. 扩展函数：获取直接子类型
Resolver.getDirectSubclasses(ksClass: KSClassDeclaration)

// 5. 创建类型 alias
Resolver.createKSType(javaType: Type)

// build.gradle.kts
 kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xplugin=" +
            "$kspPluginJar${File.pathSeparator}$otherPluginJar")
        freeCompilerArgs.add("-Xallow.any.target.in.source.root")
    }
}

// 代码中指定顺序
@AutoCanonical
class FirstProcessor : SymbolProcessor { ... }

@AutoCanonical
class SecondProcessor : SymbolProcessor { ... }
// FirstProcessor 会在 SecondProcessor 之前执行

// KSVisitor<T, R> 定义
// T: 被访问的节点类型（如 KSClassDeclaration）
// R: visit 方法的返回值类型
interface KSVisitor<T, R> {
    fun visitClassDeclaration(classDeclaration: KSClassDeclaration, data: T): R
    fun visitFunctionDeclaration(function: KSFunctionDeclaration, data: T): R
    fun visitPropertyDeclaration(property: KSPropertyDeclaration, data: T): R
    fun visitAnnotation(annotation: KSAnnotation, data: T): R
    // ... 其他 visit 方法
}

// 具体 Visitor 实现示例
class MyVisitor : KSVisitorVoid {
    override fun visitClassDeclaration(decl: KSClassDeclaration, data: Unit) {
        println("Found class: ${decl.simpleName}")
        decl.getDeclaredProperties().forEach { it.accept(this, Unit) }
        decl.getDeclaredFunctions().forEach { it.accept(this, Unit) }
    }
}

// 1. IR 变换（IR Plugin）
// 插入到 Kotlin → IR → Bytecode 流水线
// Compose Compiler 就是 IR Plugin

// 2. 编译检查（Check Plugin）
// 在编译器前端执行类型检查
// 可以添加自定义警告/错误

// 3. KSP（Symbol Processor）
// 在编译前期处理注解和符号
// 生成代码或修改 AST

// 编译插件注册（plugin.yml）
// - name: org.jetbrains.kotlin.compose.compilerplugins
//   embeddedIntoCompiler: true
//   changesCompilation: true

// 1. 定义注解
@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.SOURCE)
annotation class AutoData

// 2. 实现 SymbolProcessor
class AutoDataProcessor : SymbolProcessor {
    override fun process(resolver: Resolver): List<KSNode> {
        val symbols = resolver.getSymbolsWithAnnotation(AutoData::class.qualifiedName)
        symbols.filter { it is KSClassDeclaration }
            .forEach { generateDataClass(it) }
        return symbols.toList()
    }

    private fun generateDataClass(decl: KSClassDeclaration) {
        // 生成代码...
        KSFile.createKSFile(...).appendText(generatedCode)
    }
}

// 3. 注册服务
// META-INF/services/com.google.devtools.ksp.SymbolProcessor
// com.example.AutoDataProcessor

# KSP 迁移评估
# □ 确认所有依赖库都有 KSP 版本
# □ 处理器不依赖 JVM 反射
# □ 检查 KSVisitor 是否覆盖所有节点类型
# □ 添加 @GeneratedAnnotation 支持增量
# □ 测试增量编译场景
# □ 验证所有平台的生成代码一致性