Kotlin Symbol Processing (KSP) 完全指南：安装、方法与代码生成实战

1. 什么是 KSP？为什么需要它？

Kotlin Symbol Processing (KSP) 是 JetBrains 为 Kotlin 语言打造的一款库和编译器插件。它的核心目标是提供一个简单、快速且可靠的 API，让开发者能够在编译阶段分析 Kotlin 源代码，并基于分析结果自动生成新代码（即代码生成）。KSP 是旧版 javax.annotation.processing（Java 注解处理）的直接替代方案，后者专为 Java 设计，在处理 Kotlin 时存在诸多限制。

为什么需要 KSP？在现代 Kotlin 开发中，我们经常需要自动生成大量样板代码：DTO 类、映射器、Parcelable 实现、Room 实体、Moshi 适配器等等。KSP 让你能在编译期完成这些工作，无需在运行时使用反射，从而显著提升应用性能。与 KAPT（Kotlin 注解处理工具）不同，KSP 直接操作 Kotlin 的 AST 抽象语法树，跳过了中间的 Java 转换阶段，速度提升 2 到 4 倍。此外，KSP 对 Kotlin 的新语言特性（如 suspend 函数、inline 类、value 类）支持更好，且无需生成 Java 桩代码。

KSP 非常适合用于构建自定义的代码生成库、框架（类似 Dagger、Room、Glide 的替代方案）以及元编程工具。它在 Kotlin 生态系统中被广泛使用：Compose、Room、Moshi、Koin、Apollo GraphQL 等众多流行库都基于 KSP。

2. 安装指南

KSP 的安装方式与 pip 或 npm 不同，它通过 Gradle 构建系统集成。对于 Kotlin 项目，你需要添加 KSP 插件，并确保其版本与 Kotlin 版本匹配。

在 build.gradle.kts（根项目）中添加以下配置：

// build.gradle.kts（根级别）
plugins {
    id("org.jetbrains.kotlin.jvm") version "1.9.22" apply false
    id("com.google.devtools.ksp") version "1.9.22-1.0.17" apply false
}

// build.gradle.kts（应用模块）
plugins {
    id("org.jetbrains.kotlin.jvm")
    id("com.google.devtools.ksp")
}

dependencies {
    implementation("org.jetbrains.kotlin:kotlin-stdlib:1.9.22")
    implementation("com.squareup:kotlinpoet:1.16.0") // 用于代码生成
    ksp("com.example:my-processor:1.0.0") // 你的处理器
}

对于 Gradle Groovy (build.gradle)：