KSP 快速入门
要快速入门 KSP, 你可以创建自己的处理器, 或者参考 示例代码.
添加一个处理器
要添加一个处理器, 你需要包含 KSP Gradle Plugin, 并添加对这个处理器的依赖项:
向你的
build.gradle(.kts)
文件添加 KSP Gradle Plugincom.google.devtools.ksp
:plugins { id("com.google.devtools.ksp") version "2.0.21-1.0.25" }plugins { id 'com.google.devtools.ksp' version '2.0.21-1.0.25' }添加对处理器的依赖项. 这个示例使用 Dagger. 请将它替换为你想要添加的处理器.
dependencies { implementation("com.google.dagger:dagger-compiler:2.51.1") ksp("com.google.dagger:dagger-compiler:2.51.1") }dependencies { implementation 'com.google.dagger:dagger-compiler:2.51.1' ksp 'com.google.dagger:dagger-compiler:2.51.1' }运行
./gradlew build
. 你可以在build/generated/ksp
目录下看到生成的代码.
下面是完整的示例:
创建一个你自己的处理器
创建一个空的 gradle 项目.
在根项目中指定 Kotlin plugin 版本
2.0.21
, 供其他项目模块使用:plugins { kotlin("jvm") version "2.0.21" apply false } buildscript { dependencies { classpath(kotlin("gradle-plugin", version = "2.0.21")) } }plugins { id 'org.jetbrains.kotlin.jvm' version '2.0.21' apply false } buildscript { dependencies { classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.21' } }添加一个模块, 容纳处理器.
在模块的构建脚本中, 使用 Kotlin plugin, 并在
dependencies
代码段添加 KSP API.plugins { kotlin("jvm") } repositories { mavenCentral() } dependencies { implementation("com.google.devtools.ksp:symbol-processing-api:2.0.21-1.0.25") }plugins { id 'org.jetbrains.kotlin.jvm' version '2.0.21' } repositories { mavenCentral() } dependencies { implementation 'com.google.devtools.ksp:symbol-processing-api:2.0.21-1.0.25' }你需要实现
com.google.devtools.ksp.processing.SymbolProcessor
和com.google.devtools.ksp.processing.SymbolProcessorProvider
. 你实现的SymbolProcessorProvider
将被作为一个服务装载, 负责创建你实现的SymbolProcessor
实例. 注意以下几点:实现
SymbolProcessorProvider.create()
, 负责创建一个SymbolProcessor
. 通过SymbolProcessorProvider.create()
的参数传递你的处理器需要的依赖项 (比如CodeGenerator
, 处理器选项).你的主逻辑应该在
SymbolProcessor.process()
方法中.使用
resolver.getSymbolsWithAnnotation()
, 给定一个注解的完全限定名称, 得到你希望处理的符号.KSP 的一个常见使用场景是实现一个自定义的访问器 (
com.google.devtools.ksp.symbol.KSVisitor
接口) 来操作符号. 一个简单的访问器模板是com.google.devtools.ksp.symbol.KSDefaultVisitor
.关于
SymbolProcessorProvider
和SymbolProcessor
接口实现的例子, 请参见示例项目中的以下文件.src/main/kotlin/BuilderProcessor.kt
src/main/kotlin/TestProcessor.kt
编写完你自己的处理器之后, 需要向包注册你的处理器 provider, 方法是在
src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider
中包含它的完全限定名称.
在一个项目中使用你自己的处理器
创建另一个模块, 包含一段工作程序, 用来试验你的处理器.
pluginManagement { repositories { gradlePluginPortal() } }pluginManagement { repositories { gradlePluginPortal() } }在模块的构建脚本中, 使用指定版本的
com.google.devtools.ksp
plugin, 并在依赖项中添加你的处理器.plugins { id("com.google.devtools.ksp") version "2.0.21-1.0.25" } dependencies { implementation(kotlin("stdlib-jdk8")) implementation(project(":test-processor")) ksp(project(":test-processor")) }plugins { id 'com.google.devtools.ksp' version '2.0.21-1.0.25' } dependencies { implementation 'org.jetbrains.kotlin:kotlin-stdlib:2.0.21' implementation project(':test-processor') ksp project(':test-processor') }运行
./gradlew build
. 你可以在build/generated/ksp
目录下看到生成的代码.
下面是一个构建脚本示例, 它对工作程序使用 KSP plugin:
向处理器传递选项
在 gradle 构建脚本中指定 SymbolProcessorEnvironment.options
中的处理器选项:
让 IDE 感知生成的代码
默认情况下, IntelliJ IDEA 或其他 IDE 不知道生成的代码. 因此 IDE 会将生成的符号标记为无法解析. 要让 IDE 能够理解生成的符号, 请将以下路径标记为生成的源代码根目录:
如果你的 IDE 支持资源目录, 那么还需要标记下面的路径:
在你的 KSP 使用者模块的构建脚本中, 可能还需要配置这些目录:
如果你使用 IntelliJ IDEA, 并在 Gradle plugin 中使用 KSP, 那么上面的代码段会出现以下警告:
这种情况下, 请改为使用下面的构建脚本: