在 Kotlin 项目中使用注解处理器
注解处理器在编译期分析源代码,以生成模板代码、验证用法或生成其他构件。 Kotlin 支持两种使用注解处理器的方式:
kapt 编译器插件 的工作原理是从 Kotlin 源代码生成存根文件,然后在这些存根上运行 Java 注解处理器。这一额外的存根生成步骤导致构建时间变慢,并且意味着 kapt 无法理解 Kotlin 特有的结构,例如扩展函数或空安全。
kapt 同时支持 Maven 和 Gradle。建议在所有 Maven 项目以及使用尚未采用 KSP 的处理器库(例如 MapStruct)的 Gradle 项目中使用。
KSP 框架通过以 Kotlin 优先的 API 直接读取 Kotlin 源代码,无需生成存根。它原生理解 Kotlin 特有功能,并且构建速度快于 kapt。
目前,KSP 仅官方支持 Gradle。推荐用于编写自定义处理器以及与兼容 KSP 的库(如 Dagger)协同工作。
将 kapt 与 Java 注解处理器结合使用
kapt 允许你在 Kotlin 项目中使用现有的 Java 注解处理器,而无需对处理器本身进行任何更改。
下面的示例展示了如何使用 MapStruct 注解处理器,该处理器在编译期生成 JavaBeans 之间的类型安全映射器实现。
在构建文件中应用
kapt插件并将 MapStruct 添加到dependencies部分:xml<properties> <kotlin.version>2.4.21</kotlin.version> <maven.compiler.release>17</maven.compiler.release> <mapstruct.version>1.6.3</mapstruct.version> </properties> <dependencies> <dependency> <groupId>org.mapstruct</groupId> <artifactId>mapstruct</artifactId> <version>${mapstruct.version}</version> </dependency> </dependencies> <plugin> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-plugin</artifactId> <version>${kotlin.version}</version> <extensions>true</extensions> <configuration> <annotationProcessorPaths> <annotationProcessorPath> <groupId>org.mapstruct</groupId> <artifactId>mapstruct-processor</artifactId> <version>${mapstruct.version}</version> </annotationProcessorPath> </annotationProcessorPaths> </configuration> </plugin><extensions>true</extensions>选项会自动配置 kapt。它会注册src/main/kotlin和src/test/kotlin源根目录,并添加绑定到正确生命周期阶段的kapt和compile执行,从而使kapt目标在编译之前运行。maven.compiler.release属性同时配置 Java 和 Kotlin 编译器,以便 kapt 生成的 Java 源文件针对相同的 JVM 目标进行编译。
kotlinplugins { kotlin("kapt") version "2.4.21" } dependencies { implementation("org.mapstruct:mapstruct:1.6.3") kapt("org.mapstruct:mapstruct-processor:1.6.3") }groovyplugins { id "org.jetbrains.kotlin.kapt" version "2.4.21" } dependencies { implementation "org.mapstruct:mapstruct:1.6.3" kapt "org.mapstruct:mapstruct-processor:1.6.3" }定义数据类和映射器接口:
kotlinimport org.mapstruct.Mapper import org.mapstruct.factory.Mappers data class UserDto(val id: Long, val firstName: String, val lastName: String) data class UserEntity(val id: Long, val firstName: String, val lastName: String) @Mapper interface UserMapper { fun toDto(entity: UserEntity): UserDto fun toEntity(dto: UserDto): UserEntity companion object : UserMapper by Mappers.getMapper(UserMapper::class.java) }构建项目。MapStruct 会在生成的源文件目录中生成
UserMapperImpl类。使用UserMapper伴生对象调用生成的实现:kotlinfun main() { val entity = UserEntity(id = 1L, firstName = "John", lastName = "Doe") val dto = UserMapper.toDto(entity) println(dto) // UserDto(id=1, firstName=John, lastName=Doe) }
在 Gradle 项目中使用 KSP
通过 KSP,你可以在 Gradle 项目中使用现有的注解处理器,并创建根据源代码中的注解生成代码的自定义处理器。
将 KSP 与 Java 注解处理器结合使用
对于 Gradle 项目,请使用 KSP 配合兼容的注解处理器。KSP 比 kapt 更快,并且可以原生理解 Kotlin 特有功能。请参阅已支持 KSP 的库列表。
下面的示例展示了如何使用 Dagger,这是一个编译期依赖注入框架,可为依赖关系图生成装配代码。
在
build.gradle(.kts)文件中,应用 KSP 插件并将 Dagger 添加到dependencies块中:kotlin// build.gradle.kts plugins { kotlin("jvm") version "2.4.21" id("com.google.devtools.ksp") version "2.3.12" } dependencies { implementation("com.google.dagger:dagger:2.59.2") ksp("com.google.dagger:dagger-compiler:2.59.2") }groovy// build.gradle plugins { id 'org.jetbrains.kotlin.jvm' version '2.4.21' id 'com.google.devtools.ksp' version '2.3.12' } dependencies { implementation 'com.google.dagger:dagger:2.59.2' ksp 'com.google.dagger:dagger-compiler:2.59.2' }要查找 KSP 的最新版本,请查看 GitHub Releases 页面。
使用 Dagger 注解标记 Kotlin 类:
kotlinimport javax.inject.Inject import javax.inject.Singleton import dagger.Component import dagger.Module import dagger.Provides @Singleton class UserRepository @Inject constructor() { fun getUser(): String = "John Doe" } @Module class AppModule { @Provides @Singleton fun provideUserRepository(): UserRepository = UserRepository() } @Singleton @Component(modules = [AppModule::class]) interface AppComponent { fun userRepository(): UserRepository }构建项目。Dagger 会在
build/generated/ksp目录中生成实现类,例如DaggerAppComponent。在代码中使用生成的类:kotlinfun main() { val appComponent = DaggerAppComponent.create() val userRepository = appComponent.userRepository() println("User: ${userRepository.getUser()}") // User: John Doe }
有关 Dagger 对 KSP 支持的更多信息,请参阅其文档。
创建自定义注解处理器
你可以使用 KSP API 编写在编译期生成代码的自定义注解处理器。一个新处理器需要三个模块:
- 声明自定义注解的
annotation模块。 - 实现
SymbolProcessor和SymbolProcessorProvider工厂的processor模块。SymbolProcessor包含主要逻辑,而SymbolProcessorProvider负责创建处理器并在META-INF/services/路径中注册提供程序。 - 应用 KSP 插件、依赖该处理器并使用该注解的
app模块。
有关完整的分步说明,请参阅 KSP 快速入门指南。
