在 Kotlin 專案中使用註解處理器
- 在以下情況使用 kapt:
- 你使用的是 Maven 專案。
- 你使用的是 Gradle 專案,但所需的 Java 註解處理器尚不支援 KSP。請參閱支援的程式庫清單。
- 在以下情況使用 KSP:
- 你使用的是 Gradle 專案,且所需的 Java 註解處理器支援 KSP。
- 你想要建立自己的註解處理器。
註解處理器會在編譯期分析你的原始碼,以產生樣板程式碼、驗證用法或產出其他產物。 Kotlin 支援兩種搭配註解處理器運作的方式:
kapt 編譯器外掛程式 的運作方式是從 Kotlin 原始碼產生虛設常式 (stub) 檔案,然後在這些虛設常式上執行 Java 註解處理器。這個額外的虛設常式產生步驟會使建置時間變慢,而且代表 kapt 無法理解 Kotlin 特有的建構,例如擴充函式或 null 安全性。
kapt 同時支援 Maven 和 Gradle。建議用於所有 Maven 專案,以及處理器程式庫尚未採用 KSP 的 Gradle 專案,例如 MapStruct。
KSP 架構 透過 Kotlin 優先的 API 直接讀取 Kotlin 原始碼,無需產生虛設常式。它能原生理解 Kotlin 特有的功能,且建置速度比 kapt 更快。
目前 KSP 僅對 Gradle 提供官方支援。建議用於編寫你自己的處理器,以及與相容 KSP 的程式庫(如 Dagger)搭配使用。
搭配 Java 註解處理器使用 kapt
kapt 讓您可以在 Kotlin 專案中使用現有的 Java 註解處理器,而無需對處理器本身進行任何修改。
以下範例展示如何使用 MapStruct 註解處理器,該處理器會在編譯期產生 Java bean 之間型別安全的映射器實作。
在你的建置檔中套用
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 專案中使用現有的註解處理器,並建立自己的處理器以根據原始碼中的註解產生程式碼。
搭配 Java 註解處理器使用 KSP
對於 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 快速入門指南。
