Kotlin与编译器插件
kapt、KSP与编译器插件
概述
Kotlin 编译器插件是在编译期间对代码进行自动处理的工具。它们可以生成代码、修改已有代码、或执行额外的检查。最常见的用途是注解处理——扫描代码中的注解，然后自动生成额外的源文件。Kotlin 生态中有三种主要的注解处理方式：kapt、KSP 和编译器插件。
理解编译器插件的工作原理，有助于你选择合适的工具，并理解项目中自动生成的代码从何而来。
基础概念
- kapt（Kotlin Annotation Processing Tool）：Kotlin 早期的注解处理方案，通过将 Kotlin 代码转换为 Java 存根（stub），然后交给 Java 的 APT 处理。兼容性好但速度慢
- KSP（Kotlin Symbol Processing）：Kotlin 新一代的符号处理 API，直接操作 Kotlin 的 AST，速度比 kapt 快 2 倍以上
- Compiler Plugin：直接修改编译器行为的插件，如 all-open、no-arg、serialization 等
- 注解处理：在编译期扫描注解，自动生成代码的过程
- 代码生成：根据注解或配置，自动生成 Kotlin/Java 源文件
快速上手
kapt 的基本使用
// build.gradle.kts
plugins {
kotlin("jvm") version "2.0.0"
// 添加 kapt 插件
kotlin("kapt") version "2.0.0"
}
dependencies {
// 使用 kapt 处理注解
kapt("com.google.dagger:hilt-compiler:2.50")
implementation("com.google.dagger:hilt-android:2.50")
}KSP 的基本使用
// build.gradle.kts
plugins {
kotlin("jvm") version "2.0.0"
// 添加 KSP 插件
id("com.google.devtools.ksp") version "2.0.0-1.0.21"
}
dependencies {
// 使用 ksp 处理注解（注意是 ksp 而不是 kapt）
ksp("com.example:processor:1.0.0")
implementation("com.example:annotations:1.0.0")
}KSP 比 kapt 更快，因为直接操作 Kotlin AST，不需要生成 Java 存根。
详细用法
内置编译器插件
Kotlin 自带几个常用的编译器插件：
all-open 插件
让标记了指定注解的类不再默认 final，可以被继承：
// build.gradle.kts
plugins {
kotlin("jvm") version "2.0.0"
kotlin("plugin.allopen") version "2.0.0"
}
// 配置哪些注解的类需要打开
allOpen {
annotation("com.example.OpenClass")
annotation("javax.persistence.Entity") // JPA 实体类需要被代理继承
}
// 使用自定义注解
@Target(AnnotationTarget.CLASS)
annotation class OpenClass
@OpenClass
class MyService {
// 没有 all-open 插件时，Kotlin 类默认是 final，不能被继承
// 有了 all-open，标记了 @OpenClass 的类会被编译为 open class
}no-arg 插件
为标记了指定注解的类自动生成无参构造器：
// build.gradle.kts
plugins {
kotlin("plugin.noarg") version "2.0.0"
}
noArg {
annotation("com.example.NoArg")
annotation("javax.persistence.Entity")
}
@Target(AnnotationTarget.CLASS)
annotation class NoArg
@NoArg
data class User(val name: String, val age: Int)
// 编译后会自动生成无参构造器，某些框架（如 JPA）需要serialization 插件
为标记了 @Serializable 的类自动生成序列化代码：
// build.gradle.kts
plugins {
kotlin("plugin.serialization") version "2.0.0"
}
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3")
}
// 使用
import kotlinx.serialization.*
@Serializable
data class User(val name: String, val age: Int)
// 编译器插件会自动生成 User.serializer()kapt 与 KSP 的选择
// 场景一：使用 Room 数据库
// kapt 方式
dependencies {
kapt("androidx.room:room-compiler:2.6.0")
}
// KSP 方式（推荐，更快）
dependencies {
ksp("androidx.room:room-compiler:2.6.0")
}
// 场景二：使用 Dagger/Hilt
// kapt 方式（目前 Hilt 主要支持 kapt）
dependencies {
kapt("com.google.dagger:hilt-compiler:2.50")
}
// 场景三：使用 Moshi
// kapt 方式
dependencies {
kapt("com.squareup.moshi:moshi-kotlin-codegen:1.15.0")
}
// KSP 方式
dependencies {
ksp("dev.zacsweers.moshix:moshi-kotlin-codegen:0.25.0")
}自定义 KSP 处理器
// 定义注解
@Target(AnnotationTarget.CLASS)
annotation class Factory
// 实现 SymbolProcessor
class FactoryProcessor : SymbolProcessor {
override fun process(resolver: Resolver): List<KSAnnotated> {
// 查找所有标记了 @Factory 的类
val factories = resolver.getSymbolsWithAnnotation(Factory::class.qualifiedName!!)
factories.forEach { annotated ->
val classDecl = annotated as KSClassDeclaration
// 生成工厂类代码
generateFactory(classDecl)
}
return emptyList()
}
private fun generateFactory(classDecl: KSClassDeclaration) {
val className = classDecl.simpleName.asString()
val packageName = classDecl.packageName.asString()
// 使用 CodeGenerator 生成代码
val file = FileSpec.builder("$packageName.factory", "${className}Factory")
.addFunction(FunSpec.builder("create")
.returns(ClassName(packageName, className))
.addStatement("return $className()")
.build())
.build()
// 写入文件
}
}
// 注册处理器
class FactoryProcessorProvider : SymbolProcessorProvider {
override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor {
return FactoryProcessor()
}
}常见场景
Spring Boot 项目中的插件配置
// build.gradle.kts
plugins {
kotlin("jvm") version "2.0.0"
kotlin("plugin.spring") version "2.0.0" // 包含 all-open
kotlin("plugin.jpa") version "2.0.0" // 包含 all-open + no-arg
kotlin("plugin.serialization") version "2.0.0"
}
// kotlin-spring 插件自动为以下注解的类打开：
// @Component, @Service, @Repository, @Controller, @Configuration 等
// kotlin-jpa 插件自动为以下注解的类打开并生成无参构造器：
// @Entity, @Embeddable, @MappedSuperclass 等Android 项目中的插件配置
// build.gradle.kts
plugins {
kotlin("android") version "2.0.0"
kotlin("kapt") version "2.0.0" // 或使用 KSP
kotlin("plugin.serialization") version "2.0.0"
id("com.google.devtools.ksp") version "2.0.0-1.0.21"
}
dependencies {
// Room 数据库（推荐用 KSP）
ksp("androidx.room:room-compiler:2.6.0")
// Hilt 依赖注入（目前仍需 kapt）
kapt("com.google.dagger:hilt-compiler:2.50")
// 序列化
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3")
}Lombok 与 Kotlin
// 如果项目同时使用 Lombok 和 Kotlin
plugins {
kotlin("jvm") version "2.0.0"
kotlin("kapt") version "2.0.0"
id("io.freefair.lombok") version "8.4"
}
// 注意：Kotlin 代码不能直接使用 Lombok 注解
// Lombok 只能处理 Java 代码
// 如果 Kotlin 需要调用 Lombok 生成的代码，需要使用 lombok-config 配置注意事项
- KSP 是未来方向：Google 推荐使用 KSP 替代 kapt，新项目应优先选择 KSP
- kapt 的编译速度较慢：kapt 需要生成 Java 存根，增加了编译时间
- KSP 的兼容性：不是所有注解处理器都支持 KSP，使用前需要确认
- 编译器插件顺序：如果同时使用多个编译器插件，注意它们的顺序可能影响编译结果
- 生成的代码不可见：注解处理器生成的代码通常在 build 目录下，IDE 可能需要手动标记为源码目录
- 增量编译：KSP 支持增量编译，kapt 也支持但效果不如 KSP
进阶用法
kapt 的配置选项
// build.gradle.kts
kapt {
// 启用增量编译
useBuildCache = true
// 指定注解处理器的参数
arguments {
arg("option1", "value1")
arg("room.schemaLocation", "$projectDir/schemas")
}
// 排除不需要处理的依赖
exclude(group = "com.example", module = "unused-module")
}KSP 的配置选项
// build.gradle.kts
ksp {
// 传递参数给处理器
arg("option1", "value1")
arg("room.schemaLocation", "$projectDir/schemas")
// 排除特定处理器
excludeProcessor("com.example.SomeProcessor")
}
// KSP 支持多轮处理
// 如果处理器生成了新的带注解的代码，KSP 会自动进行下一轮处理自定义编译器插件
对于高级需求，可以编写自己的 Kotlin 编译器插件：
// 编写编译器插件需要实现 ComponentRegistrar 接口
// 这属于非常高级的用法，通常只在框架开发中使用
// 示例：一个简单的编译器插件结构
class MyPluginComponentRegistrar : ComponentRegistrar {
override fun registerProjectComponents(
project: MockProject,
configuration: CompilerConfiguration
) {
// 注册 IrGenerationExtension 或 ClassBuilderInterceptorExtension
// 来修改编译过程中的代码
}
}
// 在 META-INF 中注册插件
// org.jetbrains.kotlin.compiler.plugin.ComponentRegistrar
// com.example.MyPluginComponentRegistrar