Аннотации и рефлексия в Java

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Разработчику Архитектору

Аннотации и рефлексия

★ Аннотация — метаданные, прикреплённые к объявлению (класс, метод, поле, параметр). Компилятор и фреймворки читают их для проверок, генерации кода или настройки поведения во время выполнения.

★ Рефлексия (java.lang.reflect) — инспекция и вызов классов, методов и полей во время выполнения, когда имена известны не на этапе компиляции.

Модули JPMS: ключевые слова, конфигурации и module-info. Spring и DI: Spring Framework.

Зачем это нужно в реальных проектах

Аннотации и рефлексия дают инфраструктурный "клей" между фреймворками и вашим кодом:

DI-контейнеры создают и связывают компоненты;
ORM строит маппинг между таблицами и классами;
тестовые фреймворки находят и запускают тестовые методы;
сериализаторы автоматически читают и пишут поля.

Если понимать этот слой, код с фреймворками становится предсказуемым, а диагностика ошибок ускоряется.

Встроенные аннотации

Аннотация	Назначение
`@Override`	Компилятор проверяет переопределение
`@Deprecated`	Пометка устаревшего API; можно задать `since`, `forRemoval`
`@SuppressWarnings`	Подавление предупреждений компилятора (`"unchecked"`, `"deprecation"`)
`@FunctionalInterface`	Один абстрактный метод — для лямбд
`@SafeVarargs`	Подавление предупреждений о varargs и generics

@Override
public String toString() {
    return "User{id=%d}".formatted(id);
}

Разбор:

@Override заставляет компилятор проверить, что метод действительно переопределяет родительский (Object.toString()), и защищает от опечаток.
public String toString() определяет строковое представление объекта, которое активно используется в логах и отладке.
"User{id=%d}".formatted(id) подставляет значение id в шаблон и возвращает готовую строку.
Переопределение toString() делает диагностику доменных объектов быстрее, потому что в лог попадает полезный контекст, а не ClassName@hash.

Собственная аннотация

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Timed {
    String value() default "";
}

Разбор:

@Retention(RetentionPolicy.RUNTIME) сохраняет аннотацию в runtime, чтобы её можно было читать через reflection.
@Target(ElementType.METHOD) ограничивает использование аннотации только методами.
public @interface Timed объявляет собственный тип аннотации для маркировки точек измерения времени.
String value() default "" добавляет параметр аннотации с дефолтным значением, чтобы метку можно было не указывать явно.

`@Retention`	Когда видна
`SOURCE`	Только исходник (например, для генераторов)
`CLASS`	В байт-коде, не в runtime
`RUNTIME`	Доступна через рефлексию

`@Target`	Куда можно ставить
`TYPE`	Класс, интерфейс, enum
`METHOD`, `FIELD`, `PARAMETER`	Члены и параметры
`CONSTRUCTOR`	Конструктор

Использование:

public class ReportService {
    @Timed("generate")
    public byte[] generate() { ... }
}

Разбор:

@Timed("generate") помечает метод как измеряемый и передаёт человекочитаемый тег операции.
public byte[] generate() возвращает бинарный результат (например, PDF/CSV), поэтому метрика времени особенно полезна для тяжёлых операций.
Аннотация сама по себе не исполняет код; она служит маркером для обработчика (AOP/рефлексия/интерсептор).
Такой стиль позволяет добавлять наблюдаемость без смешивания инфраструктурной логики и бизнес-кода метода.

Обработка на runtime (упрощённо):

for (Method m : ReportService.class.getDeclaredMethods()) {
    if (m.isAnnotationPresent(Timed.class)) {
        Timed t = m.getAnnotation(Timed.class);
        long start = System.nanoTime();
        m.invoke(service);
        log.info("{} took {} ms", t.value(), ...);
    }
}

Разбор:

getDeclaredMethods() возвращает все методы класса, включая непубличные, и даёт материал для сканирования аннотаций.
isAnnotationPresent(Timed.class) фильтрует только те методы, где реально стоит маркер @Timed.
getAnnotation(Timed.class) читает параметры аннотации, включая value, для подписи метрики.
System.nanoTime() фиксирует точку старта с высокой точностью для измерения длительности.
m.invoke(service) выполняет метод рефлексивно; это гибко, но медленнее прямого вызова и требует обработки исключений.

В реальных проектах ту же роль выполняют AOP (Spring @Timed, interceptors) и процессоры аннотаций при компиляции (MapStruct, Lombok — с осторожностью к зависимостям).

Повторяемые и документируемые аннотации

Иногда одна и та же аннотация нужна несколько раз на одном элементе. Для этого есть repeatable-аннотации:

@Repeatable(Roles.class)
public @interface Role {
    String value();
}

public @interface Roles {
    Role[] value();
}

Разбор:

@Repeatable(Roles.class) разрешает ставить @Role несколько раз на один и тот же элемент.
Role описывает единичную метку роли, String value() хранит её значение.
Roles — контейнерная аннотация, которую компилятор использует для упаковки повторов.
Такой механизм удобен для декларативных политик доступа, когда нужно несколько ролей на метод/класс.

Для генерации JavaDoc используйте @Documented, чтобы аннотация отображалась в документации API.

Рефлексия — основные типы

Class<?> clazz = Class.forName("com.example.User");
// или User.class

Constructor<?> ctor = clazz.getDeclaredConstructor(String.class);
Object user = ctor.newInstance("Ada");

Method setName = clazz.getMethod("setName", String.class);
setName.invoke(user, "Grace");

Field idField = clazz.getDeclaredField("id");
idField.setAccessible(true);   // обход private — осторожно
idField.setLong(user, 1L);

Разбор:

Class.forName("com.example.User") загружает класс по имени во время выполнения, когда тип неизвестен на этапе компиляции.
getDeclaredConstructor(String.class) находит конструктор с конкретной сигнатурой, а newInstance("Ada") создаёт объект динамически.
getMethod("setName", String.class) ищет публичный метод и invoke вызывает его с аргументом.
getDeclaredField("id") достаёт поле по имени; setAccessible(true) снимает Java-проверки доступа для deep reflection.
idField.setLong(user, 1L) напрямую меняет значение поля у объекта; это мощно, но требует строгого контроля и тестов.

getMethod — только public; getDeclaredMethod — все объявленные в классе.

MethodHandles как более быстрый путь

Для некоторых сценариев вместо "классической" рефлексии применяют java.lang.invoke.MethodHandle. Этот API лучше дружит с JIT и часто дает более предсказуемую производительность в повторяющихся вызовах.

Рефлексия остается проще для старта и диагностики, MethodHandle чаще выбирают в библиотеках и инфраструктурном коде.

Когда рефлексия уместна

Фреймворки — внедрение зависимостей, ORM, сериализация, JUnit.
Плагины и драйверы, загружаемые по имени класса.
Утилиты (IDE, миграции, анализ байт-кода).

Когда избегать в прикладном коде:

обычный бизнес-слой без веской причины;
hot path (медленнее прямого вызова, сложнее для JIT);
обход инкапсуляции setAccessible(true) без необходимости.

Рефлексия и модули (Java 9+)

Модуль может не открывать пакет для глубокого доступа. Типичная ошибка:

InaccessibleObjectException: module java.base does not "opens java.lang" ...

Решения в порядке предпочтения:

Публичный API вместо взлома private.
opens в module-info.java для своего кода.
Флаги JVM --add-opens только для legacy-библиотек и тестов.

Подробнее: справочник конфигураций.

Рефлексия и generics — важное ограничение

Из-за type erasure параметры обобщений частично стираются в runtime.

List<String> a = new ArrayList<>();
List<Integer> b = new ArrayList<>();
System.out.println(a.getClass() == b.getClass()); // true

Разбор:

В исходном коде a и b параметризованы разными типами (String и Integer), но после компиляции работает type erasure.
new ArrayList<>() в обоих случаях создаёт один и тот же runtime-класс ArrayList.
Проверка a.getClass() == b.getClass() даёт true, потому что информация о generic-параметре в классе стёрта.
Этот пример объясняет, почему фреймворкам часто нужны дополнительные механизмы передачи типа (Class<T>, TypeToken).

Поэтому многие фреймворки просят передавать Class<T>, TypeToken или специальные reference-объекты для сохранения типа.

Аннотации в экосистеме

Jakarta Persistence / Bean Validation — @Entity, @NotNull (рекомендации).
JUnit 5 — @Test, @ParameterizedTest (JUnit).
Spring — @Component, @Autowired, @RestController (Spring).

Аннотации не выполняют логику сами — за ними стоит обработчик (контейнер, компилятор, агент).

Аннотации и compile-time обработка

Не вся работа происходит в runtime. Часть библиотек генерирует код на этапе компиляции через annotation processing:

MapStruct генерирует мапперы DTO;
Lombok модифицирует AST;
собственные процессоры могут валидировать контракты и создавать реестры.

Это помогает снизить объем рефлексии в runtime и перенести часть ошибок на этап сборки.

Безопасность

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

Частые ошибки на старте

Ставить RetentionPolicy.SOURCE, а потом пытаться читать аннотацию через рефлексию.
Использовать setAccessible(true) как первое решение вместо нормального API.
Загружать классы по данным от пользователя без белого списка.
Смешивать бизнес-логику и инфраструктурную рефлексию в одном сервисе.

Альтернативы "чистой" рефлексии

Задача	Подход
Маппинг DTO	MapStruct, records, явные фабрики
Конфигурация	типобезопасные properties, records
Полиморфизм	интерфейсы, sealed-классы (современный Java)

Мини-чек-лист

Для аннотаций, читаемых в runtime, задан RetentionPolicy.RUNTIME.
Для инфраструктурных аннотаций указан корректный @Target.
Рефлексия изолирована в инфраструктурных слоях и хорошо покрыта тестами.
Ограничения JPMS (opens) задокументированы в проекте.

Аннотации и рефлексия в Java