Skip to content

Kotlinプロジェクトでアノテーションプロセッサを使用する ​

  • 次の場合は kapt を使用してください:
  • 次の場合は 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アノテーションプロセッサの使用方法を示しています。

  1. ビルドファイルで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ターゲットに対してコンパイルされます。
    kotlin
    plugins {
        kotlin("kapt") version "2.4.21"
    }
    
    dependencies {
        implementation("org.mapstruct:mapstruct:1.6.3")
        kapt("org.mapstruct:mapstruct-processor:1.6.3")
    }
    groovy
    plugins {
        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"
    }
  2. データクラスとマッパーインターフェースを定義します:

    kotlin
    import 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)
    }
  3. プロジェクトをビルドします。MapStructは生成されたソースのディレクトリにUserMapperImplクラスを生成します。 生成された実装を呼び出すには、UserMapperのコンパニオンオブジェクトを使用します:

    kotlin
    fun 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の使用方法を示しています。

  1. 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ページを確認してください。

  2. KotlinクラスにDaggerアノテーションを付与します:

    kotlin
    import 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
    }
  3. プロジェクトをビルドします。Daggerはbuild/generated/kspディレクトリ内にDaggerAppComponentなどの実装クラスを生成します。コード内で生成されたクラスを使用します:

    kotlin
    fun 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クイックスタートを参照してください。

次のステップ ​