Kotlin Academy · 课时

编写您的第一个 SymbolProcessor

Q: 「编写您的第一个 SymbolProcessor」这节课中我会学到什么？

实现一个 KSP 处理器，扫描带注解的类并记录它们。 你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

实现一个 KSP 处理器，扫描带注解的类并记录它们。

编写您的第一个 SymbolProcessor 是 CoddyKit 上的免费 Kotlin Academy 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Kotlin Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Kotlin Academy 课程共包含 4 节课。

项目结构

KSP 处理器位于单独的 Gradle 模块中（例如 :processor）。使用该处理器的模块应用 KSP 插件，并声明对处理器模块的 ksp 依赖。处理器模块本身则通过常规的 implementation 依赖引入 KSP API。

添加 KSP 依赖

在处理器模块的 build.gradle.kts 中：

plugins { kotlin("jvm") }
dependencies {
    implementation("com.google.devtools.ksp:symbol-processing-api:2.0.0-1.0.21")
}

SymbolProcessor 接口

实现 SymbolProcessor。主要入口点是 process(resolver: Resolver): List。请返回尚未处理的符号（例如其依赖项尚未解析的符号），以便在下一轮中再次处理。

import com.google.devtools.ksp.processing.*
import com.google.devtools.ksp.symbol.*

class MyProcessor(private val logger: KSPLogger,
                  private val codeGenerator: CodeGenerator) : SymbolProcessor {
    override fun process(resolver: Resolver): List<KSAnnotated> {
        val symbols = resolver.getSymbolsWithAnnotation("com.example.MyAnnotation")
        // process symbols here
        return emptyList()
    }
}

SymbolProcessorProvider

KSP 会通过 SymbolProcessorProvider 发现您的处理器。请在 resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider 中注册它：

class MyProcessorProvider : SymbolProcessorProvider {
    override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor =
        MyProcessor(
            logger = environment.logger,
            codeGenerator = environment.codeGenerator
        )
}

服务注册文件

在处理器模块资源目录中的准确路径处创建文件：

路径：src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider
内容：您的 SymbolProcessorProvider 类的完全限定名称

按注解解析符号

使用 resolver.getSymbolsWithAnnotation(fqn) 获取所有带有指定注解的声明。将结果筛选为您所需的声明类型（例如类声明）：

val classes = resolver
    .getSymbolsWithAnnotation("com.example.MyAnnotation")
    .filterIsInstance<KSClassDeclaration>()

验证符号

在处理之前，请验证每个符号是否都可以完整解析。类型引用尚未编译的符号无效。请从 process() 返回此类符号，以便在下一轮中重试：

val (valid, deferred) = classes.partition { it.validate() }
// process valid; return deferred

访问类声明

使用 KSVisitorVoid 访问器模式遍历类的结构。重写 visitClassDeclaration，即可访问属性、函数和嵌套类：

class MyVisitor : KSVisitorVoid() {
    override fun visitClassDeclaration(classDeclaration: KSClassDeclaration, data: Unit) {
        val name = classDeclaration.simpleName.asString()
        val props = classDeclaration.getAllProperties().toList()
        println("Class: $name, props: ${props.size}")
    }
}

从处理器记录日志

使用 KSPLogger 发出不同级别的消息。logger.error() 会使构建失败；logger.warn() 会打印警告；logger.info() 会打印一条可通过 --info 查看的信息性消息。

logger.info("Processing class: ${classDeclaration.simpleName.asString()}")
logger.error("Missing required annotation", classDeclaration)

访问符号上的注解

每个 KSDeclaration 都有一个 annotations 序列。使用 filter 和 arguments 读取注解值：

val ann = classDeclaration.annotations
    .first { it.shortName.asString() == "MyAnnotation" }
val value = ann.arguments.first { it.name?.asString() == "value" }.value as String

增量处理提示

通过 CodeGenerator.createNewFile(dependencies = ...) 将输出文件与其依赖的输入符号关联起来，并告知 KSP 这种依赖关系。这样，当所有输入都未发生更改时，KSP 就可以跳过您的处理器。

快速检查

KSP 如何发现您的 SymbolProcessorProvider 实现？

回顾：编写您的第一个 SymbolProcessor

要点：

在单独的模块中实现 SymbolProcessor 和 SymbolProcessorProvider
通过 META-INF/services/ 注册提供程序
使用 resolver.getSymbolsWithAnnotation() 查找带注解的符号
在处理前验证符号，并返回未解析的符号以便重试
使用 KSPLogger 记录构建时消息，并使用 CodeGenerator 写入文件

常见问题解答

「编写您的第一个 SymbolProcessor」课时是免费的吗？

是的 — 「编写您的第一个 SymbolProcessor」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Kotlin Academy 课程的其余内容，请升级到 CoddyKit PRO。 Kotlin Academy 课程共包含 4 节课。

「编写您的第一个 SymbolProcessor」这节课中我会学到什么？

实现一个 KSP 处理器，扫描带注解的类并记录它们。你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Kotlin Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Kotlin Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「编写您的第一个 SymbolProcessor」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Kotlin Academy 课中编写并运行代码吗？

能。每节 Kotlin Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Kotlin Academy