Использование процессоров аннотаций в проектах Kotlin

Процессоры аннотаций анализируют исходный код во время компиляции, чтобы генерировать шаблонный код, проверять использование аннотаций или создавать другие артефакты. В Kotlin поддерживаются два способа работы с процессорами аннотаций:

Плагин компилятора kapt генерирует файлы-заглушки из исходного кода Kotlin, а затем запускает процессоры аннотаций Java для этих заглушек. Этот дополнительный этап генерации заглушек замедляет сборку и означает, что kapt не может понимать специфичные для Kotlin конструкции, такие как функции-расширения или безопасность типов относительно null.

kapt поддерживает Maven и Gradle. Его рекомендуется использовать во всех проектах Maven и в проектах Gradle с библиотеками процессоров, которые ещё не перешли на KSP, например MapStruct.
Платформа KSP считывает исходный код Kotlin напрямую с помощью API, ориентированного на Kotlin, без генерации заглушек. Она изначально понимает специфичные для Kotlin возможности и выполняет сборки быстрее, чем kapt.

В настоящее время KSP официально поддерживается только в Gradle. KSP рекомендуется использовать для написания собственных процессоров и работы с совместимыми с KSP библиотеками, например Dagger.

Использование kapt с процессорами аннотаций Java

kapt позволяет использовать существующие процессоры аннотаций Java в проектах Kotlin без внесения изменений в сами процессоры.

В примере ниже показано, как использовать процессор аннотаций MapStruct, который во время компиляции генерирует типобезопасные реализации мапперов для Java-бинов.

В файле сборки примените плагин kapt и добавьте MapStruct в раздел dependencies:

<properties>
    <kotlin.compiler.jvmTarget>11</kotlin.compiler.jvmTarget>
    <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>
    <executions>
        <execution>
            <id>kapt</id>
            <goals>
                <goal>kapt</goal>
            </goals>
            <configuration>
                <sourceDirs>
                    <sourceDir>src/main/kotlin</sourceDir>
                    <sourceDir>src/main/java</sourceDir>
                </sourceDirs>
                <aptMode>stubs</aptMode>
                <annotationProcessorPaths>
                    <annotationProcessorPath>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${mapstruct.version}</version>
                    </annotationProcessorPath>
                </annotationProcessorPaths>
            </configuration>
        </execution>
    </executions>
</plugin>

Добавьте выполнение цели kapt из kotlin-maven-plugin до выполнения compile.
Настройте режим обработки аннотаций с помощью параметра aptMode.

plugins {
    kotlin("kapt") version "2.4.20"
}

dependencies {
    implementation("org.mapstruct:mapstruct:1.6.3")
    kapt("org.mapstruct:mapstruct-processor:1.6.3")
}

plugins {
    id "org.jetbrains.kotlin.kapt" version "2.4.20"
}

dependencies {
    implementation "org.mapstruct:mapstruct:1.6.3"
    kapt "org.mapstruct:mapstruct-processor:1.6.3"
}

Определите классы данных и интерфейс маппера:

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)
}

Соберите проект. MapStruct сгенерирует класс UserMapperImpl в каталоге сгенерированных исходных файлов. Используйте сопутствующий объект UserMapper, чтобы вызвать сгенерированную реализацию:
```
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)
}
```

Использование KSP в проектах Gradle

С помощью KSP можно использовать существующие процессоры аннотаций в проектах Gradle и создавать собственные процессоры, генерирующие код на основе аннотаций в исходном коде.

Использование KSP с процессорами аннотаций Java

В проектах Gradle используйте KSP с совместимыми процессорами аннотаций. KSP работает быстрее kapt и изначально понимает специфичные для Kotlin возможности. См. список библиотек, уже поддерживающих KSP.

В примере ниже показано, как использовать Dagger — платформу внедрения зависимостей на этапе компиляции, которая генерирует код связей для графа зависимостей.

В файле build.gradle(.kts) примените плагин KSP и добавьте Dagger в блок dependencies:

// build.gradle.kts

plugins {
    kotlin("jvm") version "2.4.20"
    id("com.google.devtools.ksp") version "2.3.10"
}

dependencies {
    implementation("com.google.dagger:dagger:2.59.2")
    ksp("com.google.dagger:dagger-compiler:2.59.2")
}

// build.gradle

plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.4.20'
    id 'com.google.devtools.ksp' version '2.3.10'
}

dependencies {
    implementation 'com.google.dagger:dagger:2.59.2'
    ksp 'com.google.dagger:dagger-compiler:2.59.2'
}

Добавьте к классам Kotlin аннотации Dagger:

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
}

Соберите проект. Dagger сгенерирует классы реализации, например DaggerAppComponent, в каталоге build/generated/ksp. Используйте сгенерированный класс в коде:
```
fun main() {
    val appComponent = DaggerAppComponent.create()
    val userRepository = appComponent.userRepository()
    println("User: ${userRepository.getUser()}")
    // User: John Doe
}
```

Дополнительные сведения о поддержке KSP в Dagger см. в документации.

Создание собственного процессора аннотаций

С помощью API KSP можно написать собственные процессоры аннотаций, генерирующие код во время компиляции. Для нового процессора требуются три модуля:

Модуль annotation, в котором объявляется пользовательская аннотация.
Модуль processor, реализующий фабрики SymbolProcessor и SymbolProcessorProvider. SymbolProcessor содержит основную логику, а SymbolProcessorProvider создаёт процессор и регистрирует поставщика в пути META-INF/services/.
Модуль app, в котором применяется плагин KSP, зависит от процессора и использует аннотацию.

Полные пошаговые инструкции см. в кратком руководстве по KSP.

Что дальше

12 августа 2026

© 2010–2026 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/jvm-annotation-processors.html