Создание и тестирование процессоров аннотаций (с кодогенерацией) для Kotlin

В разработке с использованием Kotlin (или Java) для создания классов по верхнеуровневому описанию часто используется маркировка аннотациями (например, для моделей таблиц баз данных, сетевых запросов или инъекции зависимостей) и подключение процессоров аннотаций, которые также могут генерировать код, доступный из основного проекта. Запуск процессоров аннотаций выполняется внутри gradle (для Java-проектов через annotationProcessor, для Kotlin — kapt) и встраивается как зависимость для целей сборки проекта. И конечно же, как и для любого другого кода, для процессора аннотаций необходимо иметь возможность разрабатывать тесты. В этой статье мы рассмотрим основы использования кодогенерации (с использованием kapt) и разработки тестов для созданных генераторов кода. Во второй части статьи речь пойдет о разработке процессоров на основе Kotlin Symbol Processing (KSP) и созданию тестов для них.

Начнем с классического механизма кодогенерации kapt (Kotlin Annotation Processing Tool). kapt встраивается в gradle (как плагин) или в maven (через добавление <goals><goal>kapt</goal></goals> в описание execution в конфигурации проекта). В общем виде конфигурация проекта с kapt может быть такой:

plugins {     kotlin("jvm") version "1.8.20"     kotlin("kapt") version "1.8.20"     application }  group = "tech.dzolotov" version = "1.0-SNAPSHOT"  repositories {     mavenCentral() }  kotlin {     jvmToolchain(17) }  application {     mainClass.set("MainKt") }

После подключения кодогенерации на kapt становится возможным подключать процессоры через команду kapt, например подключен кодогенерацию Autovalue для создания иммутабельных классов (фактически в Kotlin они могут быть реализованы через data‑классы и AutoValue решает ту же задачу для Java и во многом похож на Lombok, но работает иначе).

dependencies {     implementation("com.google.auto.value:auto-value-annotations:1.10.1")     kapt("com.google.auto.value:auto-value:1.10.1") }

Kapt-процессор работает аналогично процессору аннотаций для Java, но при этом сначала исходный текст Kotlin преобразуется в Java-код и потом передается генератору. Это в целом снижает скорость кодогенерации (даже по сравнению с проектом на Java) и для решения этой проблемы и создавался альтернативный механизм KSP, о котором мы поговорим далее. В принципе кодогенерация может создавать код не только на Java, но и на Kotlin или любом другом языке, но многие используемые с kapt генераторы разработаны изначально для Java (например, Room, Hilt и т.п.).

Добавим простой класс для описания пользователей с автоматическим определением идентификатора:

import com.google.auto.value.AutoValue  @AutoValue abstract class UserInfo {     abstract fun getId(): Int     abstract fun getLogin(): String     abstract fun getPassword(): String      companion object {         var id = 0         fun create(login:String, password:String):UserInfo {             id++             return AutoValue_UserInfo(id, login, password)         }     } }

Для выполнения кодогенерации запустим задачу gradle (:

./gradlew kaptKotlin

Сгенерированный код в большинстве размещается в build-каталоге (build/generated/source/kapt/main) и представляет из себя исходный текст на Java (кроме создания get-методов, также переопределяет equals, hashCode и toString). Отдельно импортировать его нет необходимости, поскольку размещается в том же пакете, где находится исходный аннотированный класс. Созданный класс будет помечен аннотацией @Generated с указанием класса процессора, который создал этот класс:

@Generated("com.google.auto.value.processor.AutoValueProcessor") final class AutoValue_UserInfo extends UserInfo {   //определения полей   //get-функции   //toString, equals, hashCode }

Теперь сделаем пример кода для использования сгенерированного класса:

fun main() {     val users = mutableListOf<UserInfo>()     users.add(UserInfo.create("user1", "password1"))     users.add(UserInfo.create("user2", "password2"))     println(users) }

Результатом будет строковое представление списка:

[UserInfo{id=1, login=user1, password=password1}, UserInfo{id=2, login=user2, password=password2}]

Теперь разберемся с созданием собственного кодогенератора. За основу будем использовать шаблон из трех модулей (модуль с приложением, который будет использовать процессор аннотаций, модуль с аннотацией и модуль процессора). Определим аннотацию для использования в кодогенераторе:

@Retention(AnnotationRetention.SOURCE) annotation class SampleAnnotation

И реализуем сам процессор, который будет определяться в методе process в классе-расширения от javax.annotation.processing.AbstractProcessor:

@AutoService(Processor::class) @SupportedSourceVersion(SourceVersion.RELEASE_17) @SupportedAnnotationTypes("kaptexample.annotation.SampleAnnotation") class SampleAnnotationProcessor : AbstractProcessor() {     override fun process(annotations: MutableSet<out TypeElement>, roundEnv: RoundEnvironment): Boolean {         roundEnv.getElementsAnnotatedWith(SampleAnnotation::class.java).forEach {             processingEnv.messager.printMessage(Diagnostic.Kind.WARNING, "${it.simpleName} is processed.")         }         return true     } }

Здесь используется библиотека auto-service для автоматической регистрации класса, как процессора кодогенерации (подключается в build.gradle.kts):

dependencies { //...     implementation("com.google.auto.service:auto-service:1.0.1")     kapt("com.google.auto.service:auto-service:1.0.1") }

Метод process будет вызываться при обнаружении аннотаций, перечисленных в @SupportedAnnotationTypes и может иметь доступ к определениям исходного кода через реализацию RoundEnvironment (получает в roundEnv). Также внутри AbstractProcessor есть доступ к processingEnv, через который можно получать аргументы для kapt (через options), создавать файлы (через поле filer) и выводить сообщения в IDE и консоль gradle (для сообщения указывается тип из перечисления Diagnostics.Kind: ERROR — при ошибке, WARNING отображается как информационное сообщение, OTHER — для любого другого типа сообщения, не прерывающего выполнение кодогенерации). Через roundEnv можно получить информацию об аннотированных определениях (может быть перед пакетом, интерфейсом/классом, функцией/методом, или определением переменной), каждое определение представлено реализацией интерфейса Element и позволяет получить метаинформацию об определении:

• simpleName — название (без пакета)

• kind — тип элемента (определены в ElementKind)

• getAnnotation(type) — получение объекта аннотации (вместе с аргументами, если определены)

• modifiers — модификаторы определения (например, private или static)

• enclosingElement — дает доступ к элементу верхнего уровня (например, определению класса для аннотированного метода)

• enclosedElements — возвращает список вложенных элементов (например, определений свойств и методов для аннотированного класса)

Определим простой класс (аннотация @JvmField здесь используется для исключения автоматической генерации get-методов).

@SampleAnnotation class SampleClass {     @JvmField     val x: Int = 0     @JvmField     val y: Int = 0 }

и создадим процессор, который будет обнаруживать и отображать все найденные свойства класса:

@AutoService(Processor::class) @SupportedSourceVersion(SourceVersion.RELEASE_17) @SupportedAnnotationTypes("kaptexample.annotation.SampleAnnotation") class SampleAnnotationProcessor : AbstractProcessor() {     override fun process(annotations: MutableSet<out TypeElement>, roundEnv: RoundEnvironment): Boolean {         roundEnv.getElementsAnnotatedWith(SampleAnnotation::class.java).forEach { outer ->             outer.enclosedElements.forEach {inner ->                 if (inner.kind== ElementKind.FIELD) {                     processingEnv.messager.printMessage(                         Diagnostic.Kind.WARNING,                         "Field ${inner.simpleName}, modifier: ${inner.modifiers}"                     )                 }             }         }         return true     } }

Теперь добавим генерацию кода, для этого получим объект Filer и через него мы можем создать байт-код (createClassFile), ресурс (createResource) или сгенерировать новый файл с исходными текстами (createSourceFile). Далее к созданному файлу можно получить доступ через writer и записать туда сгенерированный исходный текст (после завершения работы, созданный файл будет проверен на корректность синтаксиса). Например, мы хотим добавить поле id с автоматическим увеличением, для этого сначала подготовим шаблон исходного кода (на Java, но можно и на Kotlin):

public class GeneratedSampleClass {   GeneratedSampleClass(<список полей>) {     //заполнение полей по значениям из конструктора   }   static int id = 0;   int getId() {     id++;     return id;   }   //здесь подставляем определение полей из исходного класса }

 используя шаблон и информацию из обнаруженных объектов (название пакета извлекается из enclosingElement для аннотированного класса, название и сигнатуры определения полей из enclosedElements от класса)

@AutoService(Processor::class) @SupportedSourceVersion(SourceVersion.RELEASE_17) @SupportedAnnotationTypes("kaptexample.annotation.SampleAnnotation") class SampleAnnotationProcessor : AbstractProcessor() {     override fun process(annotations: MutableSet<out TypeElement>, roundEnv: RoundEnvironment): Boolean {         roundEnv.getElementsAnnotatedWith(SampleAnnotation::class.java).forEach { outer ->             val fields = mutableListOf<Element>()              var pkgName:String? = null             val pkg = outer.enclosingElement             if (pkg.kind==ElementKind.PACKAGE && pkg.toString()!="unnamed package") {                 pkgName = pkg.toString()             }             processingEnv.messager.printMessage(Diagnostic.Kind.WARNING, "Package is $pkgName")              outer.enclosedElements.forEach { inner ->                 if (inner.kind == ElementKind.FIELD) {                     fields.add(inner)                     processingEnv.messager.printMessage(                         Diagnostic.Kind.WARNING,                         "Field ${inner.simpleName}, modifier: ${inner.modifiers}"                     )                 }             }             processingEnv.messager.printMessage(Diagnostic.Kind.WARNING, processingEnv.options.toString())             val className = "Generated${outer.simpleName}"             val classFile = processingEnv.filer.createSourceFile(className)             classFile.openWriter().use {                 val varFields = fields.map { "${it.asType()} ${it.simpleName}" }                 var initFields = fields.map { "this.${it.simpleName} = ${it.simpleName};" }                 val definitions = mutableListOf<String>()                 fields.map { field ->                     //добавляем модификатор для доступа к полю (и исключаем дублирование)                     val accessModifiers = listOf("public", "private", "protected")                     definitions.add("public ${field.modifiers.filter { !accessModifiers.contains(it.toString())}.joinToString(" ")} ${field.asType()} ${field.simpleName};")                 }                 it.write(                     """                     ${if (pkgName!=null) "package $pkgName;" else ""}                      public class $className {                                            public $className(${varFields.joinToString(",")}) {                         ${initFields.joinToString("\n")}                       }                                            static int id = 0;                       public int getId() {                         id++;                         return id;                       }                       //здесь подставляем определение полей из исходного класса                       ${definitions.joinToString("\n")}                     }                 """.trimIndent()                 )             }         }         return true     } }

Здесь дополнительно заменяются модификаторы доступа на public (чтобы тест в дальнейшем мог прочитать поля, альтернативно можно добавить генерацию get-методов). Также важно, чтобы сам класс и конструктор были public, иначе возникнет ошибка на этапе создания объекта через рефлексию. Аналогично можно сгенерировать любые структуры данных и фрагменты кода.

Для генерации кода также можно использовать библиотеки, например JavaPoet дает возможность представлять код в виде дерева объектов и генерировать форматированный код на языке Java.

Теперь перейдем к тестированию разработанного кодогенератора. Для этого подключим библиотеку kotlin-compile-testing и добавим наш проект для

dependencies {   testImplementation("com.github.tschuchortdev:kotlin-compile-testing:1.5.0") }

Библиотека позволяет выполнить программную компиляцию заданного фрагмента кода на Java или Kotlin (при этом можно добавлять процессоры аннотаций, в том числе KSP). Важно добавить в компиляцию файл с определением аннотации, поскольку при сборке библиотека не знает о существовании gradle-проектов и работает непосредственно с фрагментом кода.

Начнем с простой проверки небольшого класса без использования кодогенерации:

     @Test     fun testSimpleCode() {         val result = KotlinCompilation().apply {             sources = listOf(SourceFile.kotlin("MySimpleTest.kt", """                 class Calculator {                     fun sum(a:Int, b:Int) = a+b                 }             """.trimIndent()))         }.compile()         assertEquals(KotlinCompilation.ExitCode.OK, result.exitCode)     }

Полученный объект result содержит информацию о сгенерированных файлах в поле generatedFiles (в данной случае только исходный текст, байт-код и META-INF), также можно узнать результат компиляции (exitCode), получить список файлов, созданных процессорами аннотаций (sourcesGeneratedByAnnotationProcessor), а также получить доступ к загрузчику классов для рефлексии по созданному классу и создания его экземпляров через конструкторы и newInstance. Добавим тесты сигнатуры метода sum и проверим функциональность созданного класса:

    fun testSimpleCode() {         val result = KotlinCompilation().apply {             sources = listOf(SourceFile.kotlin("MySimpleTest.kt", """                 class Calculator {                     fun sum(a:Int, b:Int) = a+b                 }             """.trimIndent()))         }.compile()         assertEquals(KotlinCompilation.ExitCode.OK, result.exitCode)         val calculatorDescription = result.classLoader.loadClass("Calculator")         assertDoesNotThrow("Sum method is defined") { calculatorDescription.getDeclaredMethod("sum", Int::class.java, Int::class.java) }         val calculatorInstance = calculatorDescription.constructors.first().newInstance()         assertEquals(8, calculatorDescription.getDeclaredMethod("sum", Int::class.java, Int::class.java).invoke(calculatorInstance, 3, 5))     }

Тут важно помнить, что создание объектов, выполнение методов и доступ к свойств учитывает модификаторы доступности и, поскольку код теста сейчас находится в другом пакете, то нужно следить чтобы соответствующие модификаторы были public.

Теперь перейдем к тестированию нашего кодогенератора. Для добавления процессоров аннотаций в объекте класса KotlinCompilation (или JavaCompilation) есть список в свойстве annotationProcessors:

    @Test     fun testCodegen() {         val result = KotlinCompilation().apply {             annotationProcessors = listOf(SampleAnnotationProcessor())             val source = SourceFile.kotlin("MyTestClass.kt", """                 import kaptexample.annotation.SampleAnnotation                                  @SampleAnnotation                 class MyTestClass {                     val x:Int = 1                     val y:Double = 0.0                 }             """.trimIndent())             //подключаем аннотацию             val ann = SourceFile.fromPath(File("../kapt-example-core/src/main/kotlin/kaptexample/annotation/Sample.kt"))             this.sources = listOf(source, ann)         }.compile()         //проверим успешность компиляции         assertEquals(KotlinCompilation.ExitCode.OK, result.exitCode)     } 

Здесь исходный текст с определением аннотации (в kapt-example-core) компилируется вместе с нашим фрагментом, чтобы корректно сработал import и применение аннотации. Дальнейший тест выполняется аналогично предыдущему примеру:

    fun testCodegen() {         //...компиляция кода (из предыдущего примера)         //--------------------------------------------         //можно проверить отображенные сообщения через result.messages         //используем рефлексию для проверки результата         val rc = result.classLoader.loadClass("GeneratedMyTestClass")         assertDoesNotThrow("getId is defined") { rc.getDeclaredMethod("getId") }         assertEquals(3, rc.declaredFields.size, "Valid fields")         assertContentEquals(rc.declaredFields.map { it.name }.sorted(), listOf("x", "y", "id").sorted())         assertEquals(1, rc.declaredConstructors.size)         assertEquals(2, rc.declaredConstructors.first().parameters.size)         //создаем экземпляр объекта через конструктор         val instance = rc.constructors.first().newInstance(2, 3.0)         //здесь мы не имеем доступа к определению объекта, поэтому вызываем через invoke от метода         assertEquals(1, rc.getMethod("getId").invoke(instance))         assertEquals(2, rc.getField("x").get(instance))         assertEquals(3.0, rc.getField("y").get(instance))         //проверим создание второго экземпляра и корректное заполнение id         val instance2 = rc.constructors.first().newInstance(5, 8.0)         assertEquals(2, rc.getMethod("getId").invoke(instance2))     } 

Исходные тексты проекта можно найти в репозитории https://github.com/dzolotov/kapt-template (ветка codegen-test).

Мы рассмотрели основные вопросы по разработке процессоров аннотаций с возможностью кодогенерации для Java или Kotlin-проектов и способы тестирования корректности их работы. Во второй части статьи мы изучим новый подход к генерации кода на Kotlin с использованием Kotlin Symbol Processing (KSP) и, конечно, научимся разрабатывать тесты для KSP-процессоров.

В завершение приглашаю всех на бесплатный вебинар в рамках которого научимся проверять готовность мобильного приложения для использования людьми с ограничениями здоровья. Также готовность автоматически проверять соответствие требованиям визуальной контрастности, адаптации верстки под увеличенный шрифт, наличие семантической разметки для вспомогательных инструментов для приложений Android (XML и Compose) и iOS (Flutter и KMM). Научимся использовать инструменты автоматических проверок и создавать собственные валидаторы для реализации сложных визуальных проверок.

• Зарегистрироваться на бесплатный вебинар