04. Event Listener'ы

Зачем это нужно: проблема сильной связанности сервисов

Типичный сценарий роста бизнес-логики: оформление заказа изначально делает одно — сохраняет заказ. Через полгода к этому добавляется резервирование склада, отправка письма-подтверждения, начисление бонусных баллов, событие для аналитики, уведомление в Slack о крупном заказе. Наивный путь — звать всё это напрямую из OrderService.placeOrder():

@Service
class OrderService {

    @Transactional
    Order placeOrder(OrderRequest request) {
        Order order = orderRepository.save(Order.from(request));

        // OrderService теперь ЗНАЕТ про склад, почту, лояльность, аналитику —
        // и должен собрать все эти зависимости конструктором
        inventoryService.reserve(order);
        emailClient.sendConfirmation(order);
        loyaltyService.accruePoints(order);
        analyticsClient.track("order_placed", order.getId());

        return order;
    }
}

Проблема не только в размере конструктора. Любая из побочных реакций может упасть — и если emailClient.sendConfirmation() бросит исключение из-за недоступности SMTP-сервера, весь метод откатит транзакцию и клиент не получит своего сохранённого заказа, хотя сам заказ к отправке письма никакого отношения не имеет. Добавление новой реакции на «заказ оформлен» требует правки OrderService — сервиса, который логически про заказы, а не про склад и почту. Событийная модель разрывает эту связь: OrderService публикует факт «заказ оформлен» и не знает, кто и сколько подписчиков на него отреагирует.

Базовое использование: ApplicationEventPublisher + @EventListener

С версии Spring 4.2 событием может быть произвольный POJO — не обязательно наследовать ApplicationEvent. Достаточно объявить класс (удобно — record) и опубликовать его через ApplicationEventPublisher, который Spring внедряет как обычную зависимость (эту роль на практике исполняет сам ApplicationContext):

public record OrderPlacedEvent(Order order, Instant occurredAt) {
}

@Service
class OrderService {

    private final ApplicationEventPublisher eventPublisher;
    private final OrderRepository orderRepository;

    @Transactional
    Order placeOrder(OrderRequest request) {
        Order order = orderRepository.save(Order.from(request));
        eventPublisher.publishEvent(new OrderPlacedEvent(order, Instant.now()));
        return order;
    }
}

Подписчик — обычный компонент с методом, размеченным @EventListener; тип единственного параметра метода определяет, на какие события он подписан:

@Component
class InventoryReservationListener {

    @EventListener
    void onOrderPlaced(OrderPlacedEvent event) {
        inventoryService.reserve(event.order());
    }
}

Механика внутри: EventListenerMethodProcessor и ApplicationEventMulticaster

ApplicationEventPublisher в рантайме — это сам ApplicationContext (интерфейс ApplicationContext наследует ApplicationEventPublisher). Его метод publishEvent() не рассылает события напрямую — он делегирует единственному бину-диспетчеру, ApplicationEventMulticaster (по умолчанию — SimpleApplicationEventMulticaster):

// Упрощённо: AbstractApplicationContext.publishEvent(event)
void publishEvent(Object event) {
    ApplicationEvent applicationEvent = event instanceof ApplicationEvent ae
            ? ae
            : new PayloadApplicationEvent<>(this, event); // оборачиваем "голый" POJO
    applicationEventMulticaster.multicastEvent(applicationEvent);
}

// Упрощённо: SimpleApplicationEventMulticaster.multicastEvent(event)
void multicastEvent(ApplicationEvent event) {
    for (ApplicationListener<?> listener : getApplicationListeners(event)) {
        Executor executor = getTaskExecutor();
        if (executor != null) {
            executor.execute(() -> invokeListener(listener, event));
        } else {
            invokeListener(listener, event); // СИНХРОННО, в потоке publishEvent()
        }
    }
}

Ключевой факт — getApplicationListeners(event) отбирает подходящих слушателей по generic-типу события через ResolvableType (что позволяет и универсальным событиям вроде PayloadApplicationEvent<OrderPlacedEvent> находить нужных подписчиков), а по умолчанию у мультикастера нет Executor — то есть весь список слушателей выполняется синхронно, один за другим, в том же потоке, который вызвал publishEvent(). Метод не возвращает управление публикующему коду, пока не отработает последний слушатель.

Методы, размеченные @EventListener, сами по себе не являются бинами ApplicationListener — их туда превращает отдельный механизм:

1. При старте контекста регистрируется EventListenerMethodProcessor — SmartInitializingSingleton, который отрабатывает после создания всех синглтонов;
2. Он проходит по методам каждого бина в поисках @EventListener (и его специализаций, включая @TransactionalEventListener — см. ниже);
3. Каждый найденный метод оборачивается в ApplicationListenerMethodAdapter, который реализует ApplicationListener<ApplicationEvent> и внутри рефлективно вызывает исходный метод через бин, полученный из контекста (то есть через прокси, если он есть);
4. Адаптер регистрируется в том же ApplicationEventMulticaster, что и «ручные» реализации ApplicationListener.

Порядок выполнения и условная фильтрация

Если на одно событие подписано несколько слушателей, порядок их вызова по умолчанию не гарантирован (фактически — порядок регистрации бинов, на который нельзя полагаться). Управлять им явно позволяет @Order:

@Component
class InventoryReservationListener {

    @Order(1) // склад резервируем раньше, чем шлём письмо
    @EventListener
    void onOrderPlaced(OrderPlacedEvent event) {
        inventoryService.reserve(event.order());
    }
}

Второй практичный инструмент — атрибут condition с выражением SpEL, вычисляемым до вызова тела метода: событие доходит до слушателя, но обработка отфильтровывается декларативно, без ветвления внутри метода. Внутри выражения событие доступно как #event либо по имени параметра метода:

@Component
class FraudReviewListener {

    @EventListener(condition = "#event.order().totalAmount().compareTo(T(java.math.BigDecimal).valueOf(100000)) > 0")
    void onLargeOrder(OrderPlacedEvent event) {
        fraudCheckService.flagForManualReview(event.order());
    }
}

Асинхронные слушатели: @Async на @EventListener

Раз мультикастер по умолчанию вызывает слушателей синхронно в потоке издателя, тяжёлый или медленный слушатель (внешний HTTP-вызов, отправка письма) удерживает этот поток на всё время своей работы — в том числе поток, обслуживающий HTTP-запрос пользователя. Решение — обычный @Async поверх @EventListener (после @EnableAsync, см. тему 02 про экзекьюторы):

@Component
class AnalyticsListener {

    @Async
    @EventListener
    void onOrderPlaced(OrderPlacedEvent event) {
        // уходит в applicationTaskExecutor, не блокирует поток publishEvent()
        analyticsClient.track("order_placed", event.order().getId());
    }
}

@TransactionalEventListener: привязка к фазам транзакции

У обычного @EventListener есть скрытая опасность: если он выполняется синхронно внутри той же транзакции, что и издатель (а это дефолт), исключение в слушателе распространяется вверх и может откатить транзакцию, которая к слушателю отношения не имеет — например, отмена уже сохранённого заказа из-за упавшей отправки письма. @TransactionalEventListener решает это, привязывая вызов к конкретной фазе транзакции издателя, а не к моменту публикации:

@Component
class OrderConfirmationEmailListener {

    // Выполнится ПОСЛЕ успешного коммита транзакции OrderService.placeOrder() —
    // падение здесь уже никак не влияет на сохранённый заказ
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    void onOrderPlaced(OrderPlacedEvent event) {
        emailClient.sendConfirmation(event.order());
    }
}

Продвинутые возможности: собственный мультикастер и generic-события

Общий Executor для всех слушателей сразу, без разметки каждого @Async по отдельности — можно переопределить сам бин мультикастера под именем applicationEventMulticaster:

@Configuration
class EventingConfig {

    @Bean("applicationEventMulticaster") // имя строго зарезервировано фреймворком
    ApplicationEventMulticaster applicationEventMulticaster() {
        SimpleApplicationEventMulticaster multicaster = new SimpleApplicationEventMulticaster();
        multicaster.setTaskExecutor(Executors.newVirtualThreadPerTaskExecutor());
        return multicaster;
    }
}

Это распространяет асинхронность на все события и всех слушателей разом — удобно как глобальная политика, но менее гибко, чем точечный @Async на конкретных слушателях (и точно так же теряет порядок выполнения между слушателями, если он был важен).

Generic-события. Тип события может быть параметризован, и ResolvableType внутри мультикастера умеет находить точного подписчика на конкретный параметр:

public record EntityChangedEvent<T>(T entity, ChangeType type) {
}

@Component
class OrderCacheInvalidationListener {

    // Сработает только на EntityChangedEvent<Order>, а не на
    // EntityChangedEvent<Customer> и т.п. — резолвится по generic-параметру
    @EventListener
    void onOrderChanged(EntityChangedEvent<Order> event) {
        cacheManager.evict("orders", event.entity().getId());
    }
}

Сравнение способов подписки на события

Когда применять, когда избегать

Применять события стоит, когда:

• на один бизнес-факт («заказ оформлен», «платёж прошёл») реагирует несколько независимых друг от друга частей системы, и издатель не обязан о них знать;
• побочный эффект необязателен для успеха основной операции и не должен блокировать/откатывать её — прямой кандидат на @TransactionalEventListener(AFTER_COMMIT) или @Async;
• нужно точечно расширить поведение модуля без правки его кода — новый слушатель подключается, ничего не трогая в издателе (полезно на границах модулей монолита, в духе Spring Modulith).

Избегать стоит, когда:

• реакция обязана быть частью той же атомарной транзакции, что и издатель, и без неё вся операция должна считаться неуспешной — тогда это часть основной бизнес-логики, а не побочный эффект, зовите напрямую, а не через событие;
• порядок выполнения нескольких слушателей критичен для корректности и не выражен явно через @Order — неявный порядок хрупок и рассыпается при добавлении нового слушателя;
• событие должно пережить рестарт сервиса, дойти до другого сервиса/инстанса или быть повторно обработано после сбоя — задача не для in-process событий, а для персистентного брокера сообщений с паттерном transactional outbox;
• цепочка «событие → слушатель публикует новое событие → следующий слушатель» разрастается настолько, что бизнес-поток невозможно проследить по коду одним чтением сверху вниз («event soup») — иногда явный последовательный вызов читается и отлаживается проще, чем красиво развязанная, но неотслеживаемая цепочка событий.

Как тестировать

Начиная со Spring Framework 5.3.3 есть штатная поддержка записи опубликованных событий в тесте — аннотация @RecordApplicationEvents вместе с автоматически доступным бином ApplicationEvents:

@SpringBootTest
@RecordApplicationEvents
class OrderServiceTest {

    @Autowired OrderService orderService;
    @Autowired ApplicationEvents events;

    @Test
    void placingOrderPublishesOrderPlacedEvent() {
        orderService.placeOrder(someRequest());

        assertThat(events.stream(OrderPlacedEvent.class))
                .hasSize(1)
                .first()
                .extracting(OrderPlacedEvent::order)
                .extracting(Order::getStatus)
                .isEqualTo(OrderStatus.PLACED);
    }
}

Отдельный слушатель без поднятия контекста тестируется как обычный класс — просто вызовом метода с моками зависимостей, без Spring вообще:

@Test
void reservesInventoryOnOrderPlaced() {
    InventoryReservationListener listener =
            new InventoryReservationListener(inventoryService);

    listener.onOrderPlaced(new OrderPlacedEvent(order, Instant.now()));

    verify(inventoryService).reserve(order);
}