Kotlinプロジェクトでアノテーションプロセッサを使用する
- 次の場合は kapt を使用してください:
- Mavenプロジェクトの場合。
- Gradleプロジェクトだが、必要なJavaアノテーションプロセッサがまだKSPをサポートしていない場合。サポートされているライブラリのリストを参照してください。
- 次の場合は KSP を使用してください:
- Gradleプロジェクトであり、必要なJavaアノテーションプロセッサがKSPをサポートしている場合。
- 独自のアノテーションプロセッサを作成したい場合。
アノテーションプロセッサは、コンパイル時にソースコードを解析して、ボイラープレートコードの生成、使い方の検証、またはその他のアーティファクトの生成を行います。 Kotlinは、アノテーションプロセッサを扱うための2つの方法をサポートしています:
kaptコンパイラプラグインは、Kotlinソースコードからスタブファイルを生成し、それらのスタブに対してJavaアノテーションプロセッサを実行することで機能します。このスタブ生成の余分なステップによりビルド時間が遅くなり、またkaptは拡張関数やnull安全などのKotlin固有の構造を理解できません。
kaptはMavenとGradleの両方をサポートしています。すべてのMavenプロジェクト、およびMapStructなど、まだKSPを採用していないプロセッサライブラリを使用するGradleプロジェクトで推奨されます。
KSPフレームワークは、スタブを生成することなく、KotlinファーストのAPIを通じてKotlinソースコードを直接読み取ります。Kotlin固有の機能をネイティブに理解し、kaptよりも高速にビルドを実行します。
現在、KSPの公式サポートはGradleのみです。独自のプロセッサを作成する場合や、DaggerのようなKSP互換ライブラリと連携する場合に推奨されます。
Javaアノテーションプロセッサでkaptを使用する
kaptを使用すると、プロセッサ自体に変更を加えることなく、Kotlinプロジェクトで既存のJavaアノテーションプロセッサを使用できます。
以下の例は、コンパイル時にJava beans間の型安全なマッパー実装を生成するMapStructアノテーションプロセッサの使用方法を示しています。
ビルドファイルで
kaptプラグインを適用し、dependenciesセクションにMapStructを追加します: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プラグインを適用し、dependenciesブロックにDaggerを追加します: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ページを確認してください。
KotlinクラスにDaggerアノテーションを付与します:
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を使用して、コンパイル時にコードを生成する独自のアノテーションプロセッサを作成できます。 新しいプロセッサには3つのモジュールが必要です:
- カスタムアノテーションを宣言する
annotationモジュール。 SymbolProcessorおよびSymbolProcessorProviderファクトリを実装するprocessorモジュール。SymbolProcessorにはメインロジックが含まれ、SymbolProcessorProviderはプロセッサを作成してプロバイダをMETA-INF/services/パスに登録します。- KSPプラグインを適用し、プロセッサに依存して、アノテーションを使用する
appモジュール。
完全なステップバイステップの手順については、KSPクイックスタートを参照してください。
