Обработка аннотаций в Java

Обработка аннотаций — это точка расширения в javac. Вы пишете класс — процессор аннотаций — который компилятор вызывает во время компиляции, передаёт ему обнаруженные элементы и ожидает результата. Процессор может делать две полезные вещи: валидировать аннотированный код (выдавать ошибки или предупреждения через диагностический канал javac) или записывать новые исходные файлы, которые участвуют в той же компиляции.

Фреймворки, которыми вы, вероятно, уже пользовались, работают именно на этом механизме:

Lombok переписывает аннотированные классы, добавляя геттеры, билдеры и методы equals/hashCode.
Dagger / Hilt генерируют связку dependency injection в ответ на @Inject и @Module.
Статическая метамодель Hibernate генерирует классы Entity_ для типобезопасных Criteria-запросов.
Auto-Service / Auto-Value генерируют шаблонные записи META-INF и классы-значения.
Micronaut / Quarkus генерируют связку фреймворка во время сборки, а не при запуске.

API процессора находится в javax.annotation.processing, а языковая модель — в javax.lang.model. Вместе они позволяют javac размещать сторонние инструменты времени компиляции.

Структура процессора

Процессор реализует javax.annotation.processing.Processor. На практике вы расширяете AbstractProcessor и переопределяете process(...):

import javax.annotation.processing.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.*;
import java.util.Set;

@SupportedAnnotationTypes("com.example.Marker")           // which annotations to handle
@SupportedSourceVersion(SourceVersion.RELEASE_21)
public class MarkerProcessor extends AbstractProcessor {

  @Override
  public boolean process(Set<? extends TypeElement> annotations,
                         RoundEnvironment roundEnv) {
    for (Element e : roundEnv.getElementsAnnotatedWith(Marker.class)) {
      processingEnv.getMessager().printMessage(
        javax.tools.Diagnostic.Kind.NOTE,
        "found @Marker on " + e.getSimpleName(),
        e);
    }
    return true;                                          // claim the annotation
  }
}

Две аннотации на классе объявляют, какие типы аннотаций этот процессор хочет обрабатывать и на какой языковой уровень он ориентируется. Оба значения также можно возвращать динамически из getSupportedAnnotationTypes() / getSupportedSourceVersion(), если их нужно вычислять.

process вызывается за каждый раунд. Каждый раунд — это один проход по исходным файлам; если ваш процессор создаёт новые файлы, они сами обрабатываются в следующем раунде. Цикл завершается, когда ни один раунд не создаёт новых файлов.

Языковая модель: не рефлексия

Первый сюрприз: внутри процессора у вас нет Class<?>. Классы, которые вы обрабатываете, ещё не скомпилированы. Вместо этого вы работаете с типами из javax.lang.model.element:

Element — любой элемент в исходном коде: класс, метод, поле, параметр, пакет.
TypeElement — класс, интерфейс или перечисление (элемент Element, у которого можно запросить getQualifiedName()).
ExecutableElement — метод или конструктор.
VariableElement — поле, параметр или локальная переменная.
TypeMirror — тип (как в «тип List<String>»), отличный от элемента, который его объявил.

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

Чтобы прочитать значения элементов аннотации, используйте Element.getAnnotation(MyAnn.class) (возвращает прокси, аналогично рефлексии) или Element.getAnnotationMirrors() (возвращает структурное представление, которое нужно, когда значение элемента содержит ссылку на Class на тип, который тоже компилируется в этом же раунде).

Регистрация процессора

Компилятору нужно найти ваш процессор. Есть два способа:

Файл service-loader. Поместите файл с именем META-INF/services/javax.annotation.processing.Processor в classpath процессора, содержащий полное имя класса процессора, по одному на строку. Именно это автоматически генерируют такие инструменты, как auto-service от Google.
Флаг -processor. Передайте -processor com.example.MarkerProcessor в javac (или настройте в инструменте сборки — конфигурация annotationProcessor в Gradle, <annotationProcessorPaths> в Maven).

В Maven и Gradle принято хранить процессор в собственном модуле и подключать его из основного модуля через annotationProcessor (Gradle) / <scope>provided</scope> (Maven). Процессор выполняется только во время компиляции и не поставляется в runtime.

Генерация файлов

Возможны два вида вывода:

Исходные файлы — записываются через processingEnv.getFiler().createSourceFile(name). Результат — объект JavaFileObject, в чей openWriter() вы записываете исходный код. Новый файл компилируется в следующем раунде.
Файлы ресурсов — записываются через getFiler().createResource(...) для всего, что попадает в classpath во время выполнения (например, регистрации сервисов).

Паттерн состоит в том, чтобы выводить пакет и имя нового класса из аннотированного элемента, а затем формировать исходный код в виде String:

TypeElement cls = ...;                                     // the annotated class
String pkg = elementUtils.getPackageOf(cls).getQualifiedName().toString();
String genName = cls.getSimpleName() + "Generated";

JavaFileObject src = filer.createSourceFile(pkg + "." + genName, cls);
try (Writer w = src.openWriter()) {
  w.write("package " + pkg + ";\n");
  w.write("public class " + genName + " {\n");
  w.write("  public static String origin() { return \"" + cls.getSimpleName() + "\"; }\n");
  w.write("}\n");
}

Реальный процессор, как правило, использует генератор кода, например JavaPoet (который предоставляет типизированный построитель AST), а не конкатенацию строк. Механика идентична; JavaPoet просто делает исходный код читаемым.

Ошибки, предупреждения, заметки

Процессор сообщает о диагностике через Messager:

processingEnv.getMessager().printMessage(
    Diagnostic.Kind.ERROR,
    "@Marker may only annotate top-level classes",
    element);

Kind.ERROR завершает сборку с ошибкой в указанной позиции исходного кода. WARNING, MANDATORY_WARNING и NOTE — уровни пониже. По возможности всегда передавайте аргумент Element — это даёт пользователю кликабельное местоположение в исходном коде вместо безликого блока в логе сборки.

Инкрементальная компиляция

Процессоры аннотаций — известная причина замедления сборки. Две причины:

Они могут быть неинкрементальными: если процессору не указывается, какие источники нужно перепроцессировать, инструмент сборки перепроцессирует всё при изменении любого источника.
Они могут блокировать параллелизм: раунды выполняются последовательно.

Gradle ввёл категории isolating и aggregating для процессоров, чтобы позволить им участвовать в инкрементальной компиляции. Процессор, создающий один сгенерированный файл на каждый аннотированный источник (Dagger делает это для @Component), может объявить себя «isolating», и Gradle перезапустит его только для изменённых источников. Агрегирующие процессоры — те, которые смотрят на все аннотированные элементы для создания единого файла реестра — перезапускаются при изменении любого аннотированного источника. Выбирайте категорию процессора честно; компромисс — это корректность против скорости.

Рабочий пример: имитация обработки аннотаций во время выполнения

Настоящая обработка аннотаций требует многомодульной сборки, точки расширения javac и файла сервиса — ничто из этого не помещается в одну программу. Лучшая демонстрация — это имитация во время выполнения, выполняющая ту же работу: обход аннотированных классов, их валидация и запись исходных файлов во временный каталог, как это делал бы процессор времени компиляции.

java— editable, runs on the server

import java.io.IOException;
import java.lang.annotation.*;
import java.lang.reflect.Field;
import java.lang.reflect.Method;
import java.nio.file.*;
import java.util.List;

public class AnnotationProcessingDemo {

// 1. The annotation the (simulated) processor will react to
  @Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.TYPE)
  @interface Generate {
    String suffix() default "Generated";
  }

// 2. A few annotated and unannotated classes
  @Generate
  static class Account {
    long id;
    String holder;
    double balance;
  }

@Generate(suffix = "Helper")
  static class Invoice {
    String number;
    double total;
  }

static class NotAnnotated { int ignored; }

// 3. The 'processor' — same shape as a real one, just at runtime
  static int processOne(Class<?> cls, Path outDir) throws IOException {
    Generate g = cls.getAnnotation(Generate.class);
    if (g == null) return 0;                            // skip unannotated

// 3a. Compile-time-style validation
    if (java.lang.reflect.Modifier.isAbstract(cls.getModifiers())) {
      System.out.println("   ERROR: @Generate cannot annotate abstract class " + cls.getSimpleName());
      return 0;
    }

// 3b. Inspect the 'source' (here: reflection on the loaded class)
    String pkg = cls.getPackageName();
    String genName = cls.getSimpleName() + g.suffix();
    Path file = outDir.resolve(genName + ".java");

StringBuilder src = new StringBuilder();
    src.append("package ").append(pkg).append(";\n");
    src.append("// generated from ").append(cls.getSimpleName()).append("\n");
    src.append("public final class ").append(genName).append(" {\n");
    src.append("  public static java.util.List<String> fields() {\n    return java.util.List.of(");
    String fields = String.join(", ",
        java.util.Arrays.stream(cls.getDeclaredFields())
            .map(f -> "\"" + f.getName() + "\"")
            .toList());
    src.append(fields).append(");\n  }\n");
    src.append("  public static String origin() { return \"").append(cls.getSimpleName()).append("\"; }\n");
    src.append("}\n");

Files.writeString(file, src.toString());
    System.out.println("   wrote " + file.getFileName());
    return 1;
  }

public static void main(String[] args) throws Exception {
    // 1. A fresh temp directory to play the role of getFiler()
    Path outDir = Files.createTempDirectory("apt-demo-");
    System.out.println("1. output directory: " + outDir);

// 2. The candidates for processing
    List<Class<?>> roots = List.of(Account.class, Invoice.class, NotAnnotated.class);
    System.out.println("\n2. classes seen by the processor: " + roots.stream().map(Class::getSimpleName).toList());

// 3. Process them, generating files for the annotated ones
    System.out.println("\n3. processing rounds:");
    int generated = 0;
    for (Class<?> c : roots) {
      System.out.println("-- " + c.getSimpleName() + " @Generate? " + c.isAnnotationPresent(Generate.class));
      generated += processOne(c, outDir);
    }
    System.out.println("\n   generated " + generated + " source file(s)");

// 4. Show the generated content
    System.out.println("\n4. generated files:");
    try (var stream = Files.list(outDir)) {
      for (Path p : stream.toList()) {
        System.out.println("   --- " + p.getFileName() + " ---");
        Files.readString(p).lines().forEach(line -> System.out.println("     " + line));
      }
    }

// 5. Cleanup
    try (var s = Files.list(outDir)) { for (Path p : s.toList()) Files.delete(p); }
    Files.delete(outDir);
    System.out.println("\n5. cleaned up " + outDir);
  }
}

Что можно вынести из запуска:

Процессор обошёл три класса и обработал два — именно так работает RoundEnvironment.getElementsAnnotatedWith(Generate.class) в реальном процессоре javac. Третий класс был молча пропущен, поскольку его аннотация отсутствовала. Вот эта модель: процессор получает набор элементов за раунд и выполняет работу только для тех, которые его интересуют.
Каждый сгенерированный файл нёс пакет исходного класса и производное имя. В javax.lang.model вы вычисляете пакет из elementUtils.getPackageOf(typeElement).getQualifiedName(), а имя — из typeElement.getSimpleName(); здесь мы использовали Class.getPackageName() и Class.getSimpleName() как аналог. Структура переносится.
Элемент suffix давал настройку для каждого использования: Account породил AccountGenerated, Invoice — InvoiceHelper. Элементы аннотации — это главная ручка управления, которую вы предоставляете пользователю; значения по умолчанию делают типичный случай лаконичным, а именованные элементы дают точный контроль там, где он нужен.
Имитированная валидация вывела строку ERROR: для абстрактных классов. В реальном процессоре это было бы messager.printMessage(Diagnostic.Kind.ERROR, "...", element), и сборка завершилась бы с ошибкой в позиции исходного кода пользователя. Диагностика — это полноценная функциональность, а не запасной вариант — используйте её каждый раз, когда аннотация применяется неправильно, никогда не throw.
Сгенерированный исходный код не содержит ничего хитрого — List.of(...) с именами полей и вспомогательный метод origin(). Это типично. Ценность генерации во время компиляции редко заключается в хитрости результата; она в том, что результат существует вообще, до запуска программы, там, где в противном случае потребовалась бы рефлексия во время выполнения (и её стоимость).

Когда стоит использовать процессор

Процессор оправдывает себя, когда:

В противном случае вы бы писали один и тот же шаблонный код вручную для каждого аннотированного класса.
Работу можно выполнить только по сигнатурам исходного кода (реальное поведение экземпляров не нужно).
Альтернатива во время выполнения использовала бы рефлексию при каждом вызове, и эта стоимость накапливается.

Процессор — неправильный инструмент, когда:

Вы хотите изменить существующий класс. Стандартные процессоры могут только добавлять новые исходные файлы; они не переписывают аннотированный класс. (Lombok переписывает, подключаясь к внутреннему AST javac, что неофициально и ненадёжно.)
Нужные метаданные существуют только во время выполнения (область запроса, идентификация пользователя, конфигурация, загружаемая с диска).
Простой рефлексивный поиск при запуске сделал бы то же самое в 50 строк.

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

Конец части 16

На этом заканчивается часть книги об аннотациях. Мы рассмотрели, что такое аннотация — чистые метаданные, отдельные от кода, который выполняется, — затем небольшой набор, предоставляемый стандартной библиотекой, пять мета-аннотаций, которые настраивают ваши собственные, рецепт объявления пользовательской аннотации и, наконец, API обработки во время компиляции, который фреймворки используют для работы с аннотациями во время сборки.

Мысленная модель для дальнейшего использования: аннотация никогда ничего не делает сама по себе. Что-то другое читает её и решает действовать. Это «что-то другое» — либо компилятор (встроенные проверки), либо процессор аннотаций (генерация кода во время компиляции), либо ваш собственный код через рефлексию (фреймворки времени выполнения). Когда аннотация ведёт себя не так, как ожидается, первый вопрос всегда: кто должен её читать?

Следующая часть книги — Рефлексия — сторона API времени выполнения, которую вы уже начали использовать для чтения аннотаций.

Практика

Процессор аннотаций генерирует исходный файл 'Module', агрегирующий каждый класс, аннотированный `@Service`. Сборки замедляются, потому что каждое редактирование любого источника запускает полную повторную обработку. Какая классификация Gradle наиболее подходящая?

`aggregating` — потому что результат зависит от полного набора аннотированных элементов (он 'агрегирует' их). Инструмент сборки не может безопасно пропустить процессор при изменении любого аннотированного источника`isolating` — Gradle запустит его один раз для каждого аннотированного источника, а затем объединит результаты`dynamic` — процессор будет запускаться только при явном вызове из CLI`incremental` — Gradle сравнит результат и выдаст только изменения