AP и KSP: генерация builder для DTO¶

В этом руководстве вы реализуете небольшой генератор: @GenerateBuilder создаёт fluent builder для immutable DTO. Вы прочитаете структуру DTO, сгенерируете типизированные методы и вызов конструктора и выдадите диагностику неподдерживаемого ввода при компиляции. Реализации Java и Kotlin используют те же базовые обработчики, что и сама Kora.

Что вы создадите¶

Общий артефакт аннотации @GenerateBuilder
Java-обработчик на AbstractKoraProcessor и Kotlin-обработчик на BaseSymbolProcessor
CreateUserBuilder с методами name(...), email(...) и build()
Запускаемый консольный пример, диагностики и инкрементальные метаданные

Что потребуется¶

JDK 25 или новее, Gradle Wrapper 9+ и редактор
Kotlin 2.4.20 и KSP 2.3.12 для ветки Kotlin
Артефакты processor-common Kora 2.0.0.RC2
Знакомство с Java record или Kotlin data class

Требования¶

Самостоятельный пример обработчика

Используйте вводное руководство для настройки JDK и Wrapper. Создайте отдельный проект и выберите Java или Kotlin для исходников приложения. Полные скрипты ниже настраивают консольное приложение.

Модуль Neo4j показывает обычное runtime-подключение; этот пример отдельно обучает генерации исходников. Работающий граф и внешняя инфраструктура не требуются. Команды выполняются из корня нового проекта.

Обзор¶

При нескольких параметрах одного типа именованные вызовы builder делают место создания DTO понятнее позиционного конструктора. Обработчик убирает повторяющийся код builder, сохраняя объявленные типы полей DTO. Новое поле меняет сгенерированный API при следующей компиляции.

Runtime и артефакты обработчиков¶

builder-annotation содержит только аннотацию. Приложение подключает её через implementation; compiler helpers принадлежат только builder-annotation-processor или builder-symbol-processor. Builder — обычный объект, создаваемый в месте использования. Ему не нужны @Component и узел графа.

Подход обработчиков Kora¶

Java наследует AbstractKoraProcessor, объявляет поддерживаемые ClassName и получает сгруппированные AnnotatedElement. Kotlin наследует BaseSymbolProcessor, реализует processRound и откладывает неразрешённые символы через validateAll. Оба обработчика проверяют модель, создают тип через Poet и привязывают диагностики к исходному объявлению. Service entries позволяют компилятору обнаружить обработчики.

Поддерживаемые модели и обязательные поля¶

Java поддерживает публичные record верхнего уровня в именованном пакете, без параметров типов, с хотя бы одним компонентом. Kotlin поддерживает публичные data class верхнего уровня без параметров типов, с публичным primary constructor и обязательными non-null val параметрами. Kotlin var, nullable, default-valued и vararg параметры отвергаются. Компонент Java record Object equals также отвергается: его fluent setter конфликтовал бы с Object.equals(Object). Диагностика указывает на компонент, а не на некорректный сгенерированный файл.

Все поля builder обязательны. В Java ссылочные поля не могут быть null при build(); примитивное состояние хранится в boxed-типе, поэтому незаданный int отличается от явно переданного 0. В Kotlin используется nullable private state и requireNotNull перед созданием DTO. Это контракт builder; прямой конструктор Java record не меняется.

Аннотация и DTO¶

Java Kotlin

Создайте builder-annotation/src/main/java/example/builder/GenerateBuilder.java:

package example.builder;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.CLASS)
public @interface GenerateBuilder {}

Создайте builder-annotation/src/main/kotlin/example/builder/GenerateBuilder.kt:

package example.builder

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.BINARY)
annotation class GenerateBuilder

Политика CLASS / BINARY подходит для обнаружения при компиляции и контракта изолирующего AP. Объявите DTO:

Java Kotlin

src/main/java/example/app/CreateUser.java:

package example.app;

import example.builder.GenerateBuilder;

@GenerateBuilder
public record CreateUser(String name, String email) {}

src/main/kotlin/example/app/CreateUser.kt:

package example.app

import example.builder.GenerateBuilder

@GenerateBuilder
data class CreateUser(val name: String, val email: String)

Зависимости и структура проекта¶

Выберите язык исходников приложения, затем один Gradle DSL. Язык исходников и скрипта независимы; в каждом проекте сохраняйте только один скрипт сборки.

Корневой settings:

Java Kotlin

Groovy — settings.gradleKotlin DSL — settings.gradle.kts

rootProject.name = "builder-guide"
include("builder-annotation", "builder-annotation-processor")

rootProject.name = "builder-guide"
include("builder-annotation", "builder-annotation-processor")

Groovy — settings.gradleKotlin DSL — settings.gradle.kts

rootProject.name = "builder-guide"
include("builder-annotation", "builder-symbol-processor")

rootProject.name = "builder-guide"
include("builder-annotation", "builder-symbol-processor")

Корневой скрипт приложения:

Java Kotlin