12.4 Kotlin 符号处理 API on 编程那些事儿

12.4.1 Kotlin Symbol Processing API

Sun, 13 Sep 2026 08:50:47 +0800

原文链接: https://kotlinlang.org/docs/ksp-overview.html

12.4.1 Kotlin Symbol Processing API

Kotlin Symbol Processing（KSP）是一个针对 Kotlin 的源码生成框架。借助 KSP API，你可以创建处理器，根据源码中的注解生成代码。

KSP 的目标是简化轻量级编译器插件的创建。它定义良好的 API 隐藏了编译器的变化，因此你无需花太多精力维护处理器。不过，这种方式也有取舍。例如，基于 KSP 的处理器无法检查表达式或语句，也无法修改源代码。

12.4.2 KSP 快速入门

Sun, 13 Sep 2026 08:50:47 +0800

原文链接: https://kotlinlang.org/docs/ksp-quickstart.html

12.4.2 KSP 快速入门

在本指南中，你将学到：

如何把基于 KSP 的注解处理器添加到项目中。
如何使用 KSP API 创建你自己的注解处理器。
在哪里找到处理器生成的代码。

在项目中接入基于 KSP 的处理器

要在项目中使用外部处理器，请在你的 build.gradle(.kts) 文件的 plugins {} 块中添加 KSP。如果该处理器只在某个特定模块中需要，请把它添加到该模块的 build.gradle(.kts) 文件中：

12.4.3 从 kapt 迁移到 KSP

Sun, 13 Sep 2026 08:50:47 +0800

原文链接: https://kotlinlang.org/docs/ksp-kapt-migration.html

12.4.3 从 kapt 迁移到 KSP

在本指南中，你将学习如何把注解处理器从 kapt 迁移到 KSP，从而让项目充分利用 Kotlin 特性并提升构建性能。

kapt（Kotlin 注解处理工具）是一个有用的工具，让你可以在 Kotlin 中使用 Java 注解处理器。它的工作方式是把 Kotlin 源代码翻译成 Java “桩文件”，然后在这些桩文件上运行注解处理器。不过，这个过程开销很大，会显著增加构建时间，并且在翻译过程中会丢失一些 Kotlin 特有的特性。

12.4.4 KSP 示例

Sun, 13 Sep 2026 08:50:47 +0800

原文链接: https://kotlinlang.org/docs/ksp-examples.html

12.4.4 KSP 示例

获取所有成员函数

1
2


fun KSClassDeclaration.getDeclaredFunctions(): Sequence<KSFunctionDeclaration> =
 declarations.filterIsInstance<KSFunctionDeclaration>()

检查类或函数是否为局部声明

1
2


fun KSDeclaration.isLocal(): Boolean =
 parentDeclaration != null && parentDeclaration !is KSClassDeclaration

查找类型别名所指向的实际类或接口声明

1
2
3
4
5
6
7
8


fun KSTypeAlias.findActualType(): KSClassDeclaration {
 val resolvedType = this.type.resolve().declaration
 return if (resolvedType is KSTypeAlias) {
 resolvedType.findActualType()
 } else {
 resolvedType as KSClassDeclaration
 }
}

收集文件注解中被抑制的名称

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// @file:kotlin.Suppress("Example1", "Example2")
fun KSFile.suppressedNames(): Sequence<String> = annotations
 .filter {
 it.shortName.asString() == "Suppress" &&
 it.annotationType.resolve().declaration.qualifiedName?.asString() == "kotlin.Suppress"
 }.flatMap {
 it.arguments.flatMap {
 (it.value as Array<String>).toList()
 }
 }

12.4.5 KSP 如何为 Kotlin 代码建模

Sun, 13 Sep 2026 08:50:47 +0800

原文链接: https://kotlinlang.org/docs/ksp-additional-details.html

12.4.5 KSP 如何为 Kotlin 代码建模

你可以在 KSP GitHub 仓库中找到 API 定义。下图概览了 Kotlin 在 KSP 中的建模方式：

注意：查看全尺寸图。

类型与解析

解析占用了底层 API 实现的大部分开销。因此类型引用被设计为需要由处理器显式解析（有少数例外）。当引用一个类型（例如 KSFunctionDeclaration.returnType 或 KSAnnotation.annotationType）时，它始终是一个 KSTypeReference，即带有注解和修饰符的 KSReferenceElement。

12.4.6 Java 注解处理到 KSP 参考

Sun, 13 Sep 2026 08:50:47 +0800

原文链接: https://kotlinlang.org/docs/ksp-reference.html

12.4.6 Java 注解处理到 KSP 参考

程序元素

| Java | KSP 中最接近的设施 | 说明 |

12.4.7 增量处理

Sun, 13 Sep 2026 08:50:47 +0800

原文链接: https://kotlinlang.org/docs/ksp-incremental.html

12.4.7 增量处理

KSP 支持增量处理：只有当某个文件的一个或多个依赖发生变化时，KSP 才会重新处理该文件。这避免了不必要的重新处理，从而缩短编译时间。

12.4.8 多轮处理

Sun, 13 Sep 2026 08:50:47 +0800

原文链接: https://kotlinlang.org/docs/ksp-multi-round.html

12.4.8 多轮处理

KSP 支持多轮处理，也就是在多轮中处理文件。每轮处理的输出会作为后续各轮的额外输入。

要使用多轮处理，请让 SymbolProcessor.process() 以 List<KSAnnotated> 的形式返回被推迟的符号。KSP 会在下一轮处理这些符号。

12.4.9 在 Kotlin Multiplatform 中使用 KSP

Sun, 13 Sep 2026 08:50:47 +0800

原文链接: https://kotlinlang.org/docs/ksp-multiplatform.html

12.4.9 在 Kotlin Multiplatform 中使用 KSP

这里你将了解如何在 Kotlin Multiplatform 项目中使用 Kotlin Symbol Processing（KSP）。关于快速上手，请查看源代码仓库中一个包含多个目标并使用 KSP 的多平台项目示例。该示例中的处理器会生成项目所使用的 Foo 类。

12.4.10 从命令行运行 KSP

Sun, 13 Sep 2026 08:50:47 +0800

原文链接: https://kotlinlang.org/docs/ksp-command-line.html

12.4.10 从命令行运行 KSP

大多数项目通过 Gradle 插件使用 KSP，它会在编译期间自动运行 KSP。你也可以从命令行使用 KSP，但通常只在与其他构建系统集成、开发处理器、测试或调试时才会这么做。

12.4.11 KSP 常见问题

Sun, 13 Sep 2026 08:50:47 +0800

原文链接: https://kotlinlang.org/docs/ksp-faq.html

12.4.11 KSP 常见问题

为什么选择 KSP？

与 kapt 相比，KSP 有几个优势：

它更快。
对 Kotlin 用户来说 API 更流畅。
它支持对生成的 Kotlin 源码进行多轮处理。
它在设计时就考虑了多平台兼容性。

为什么 KSP 比 kapt 更快？

kapt 必须解析并解析每一个类型引用才能生成 Java 桩文件，而 KSP 按需解析引用。委托给 javac 也会消耗时间。