Spring Boot Event-Driven Patterns

Overview

Implement Event-Driven Architecture (EDA) patterns in Spring Boot 3.x using domain events, ApplicationEventPublisher, @TransactionalEventListener, and distributed messaging with Kafka and Spring Cloud Stream.

When to Use

• Implementing event-driven microservices with Kafka messaging

• Publishing domain events from aggregate roots in DDD architectures

• Setting up transactional event listeners that fire after database commits

• Adding async messaging with producers and consumers via Spring Kafka

• Ensuring reliable event delivery using the transactional outbox pattern

• Replacing synchronous calls with event-based communication between services

Quick Reference

Concept

Description

Domain Events

Immutable events extending DomainEvent base class with eventId, occurredAt, correlationId

Event Publishing

ApplicationEventPublisher.publishEvent() for local, KafkaTemplate for distributed

Event Listening

@TransactionalEventListener(phase = AFTER_COMMIT) for reliable handling

Kafka

@KafkaListener(topics = "...") for distributed event consumption

Spring Cloud Stream

Functional programming model with Consumer beans

Outbox Pattern

Atomic event storage with business data, scheduled publisher

Examples

Monolithic to Event-Driven Refactoring

Before (Anti-Pattern):

@Transactional

public Order processOrder(OrderRequest request) {

    Order order = orderRepository.save(request);

    inventoryService.reserve(order.getItems()); // Blocking

    paymentService.charge(order.getPayment()); // Blocking

    emailService.sendConfirmation(order); // Blocking

    return order;

}

After (Event-Driven):

@Transactional

public Order processOrder(OrderRequest request) {

    Order order = Order.create(request);

    orderRepository.save(order);

    // Publish event after transaction commits

    eventPublisher.publishEvent(new OrderCreatedEvent(order.getId(), order.getItems()));

    return order;

}

@Component

public class OrderEventHandler {

    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)

    public void handleOrderCreated(OrderCreatedEvent event) {

        // Execute asynchronously after the order is saved

        inventoryService.reserve(event.getItems());

        paymentService.charge(event.getPayment());

    }

}

See examples.md for complete working examples.

Instructions

1. Design Domain Events

Create immutable event classes extending a base DomainEvent class:

public abstract class DomainEvent {

    private final UUID eventId;

    private final LocalDateTime occurredAt;

    private final UUID correlationId;

}

public class ProductCreatedEvent extends DomainEvent {

    private final ProductId productId;

    private final String name;

    private final BigDecimal price;

}

See domain-events-design.md for patterns.

2. Publish Events from Aggregates

Add domain events to aggregate roots, publish via ApplicationEventPublisher:

@Service

@Transactional

public class ProductService {

    public Product createProduct(CreateProductRequest request) {

        Product product = Product.create(request.getName(), request.getPrice(), request.getStock());

        repository.save(product);

        product.getDomainEvents().forEach(eventPublisher::publishEvent);

        product.clearDomainEvents();

        return product;

    }

}

See aggregate-root-patterns.md for DDD patterns.

3. Handle Events Transactionally

Use @TransactionalEventListener for reliable event handling:

@Component

public class ProductEventHandler {

    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)

    public void onProductCreated(ProductCreatedEvent event) {

        notificationService.sendProductCreatedNotification(event.getName());

    }

}

Validate: Confirm the event handler fires only after the transaction commits by checking that the database state is committed before the handler executes.

See event-handling.md for handling patterns.

4. Configure Kafka Infrastructure

Configure KafkaTemplate for publishing, @KafkaListener for consuming:

spring:

  kafka:

    bootstrap-servers: localhost:9092

    producer:

      value-serializer: org.springframework.kafka.support.serializer.JsonSerializer

Validate: Send a test event via KafkaTemplate and confirm it appears in the consumer logs before proceeding to production patterns.

See dependency-setup.md and configuration.md.

5. Implement Outbox Pattern

Create OutboxEvent entity for atomic event storage:

@Entity

public class OutboxEvent {

    private UUID id;

    private String aggregateId;

    private String eventType;

    private String payload;

    private LocalDateTime publishedAt;

}

Validate: Confirm the scheduled processor picks up pending events by checking the publishedAt timestamp is set after the scheduled run.

Scheduled processor publishes pending events. See outbox-pattern.md.

6. Handle Failure Scenarios

Implement retry logic, dead-letter queues, idempotent handlers:

@RetryableTopic(attempts = "3")

@KafkaListener(topics = "product-events")

public void handleProductEvent(ProductCreatedEventDto event) {

    orderService.onProductCreated(event);

}

Validate: Confirm messages reach the dead-letter topic after exhausting retries before moving to observability.

7. Add Observability

Enable Spring Cloud Sleuth for distributed tracing, monitor metrics.

Best Practices

• Use past tense naming: ProductCreated (not CreateProduct)

• Keep events immutable: All fields should be final

• Include correlation IDs: For tracing events across services

• Use AFTER_COMMIT phase: Ensures events are published after successful database transaction

• Implement idempotent handlers: Handle duplicate events gracefully

• Add retry mechanisms: For failed event processing with exponential backoff

• Implement dead-letter queues: For events that fail processing after retries

• Log all failures: Include sufficient context for debugging

• Make handlers order-independent: Event ordering is not guaranteed in distributed systems

• Batch event processing: When handling high volumes

• Monitor event latencies: Set up alerts for slow processing

References

• dependency-setup.md — Maven/Gradle dependencies

• configuration.md — Kafka and Spring Cloud Stream configuration

• domain-events-design.md — Domain event design patterns

• aggregate-root-patterns.md — Aggregate root with event publishing

• event-publishing.md — Local and distributed event publishing

• event-handling.md — Event handling and consumption patterns

• outbox-pattern.md — Transactional outbox pattern for reliability

• testing-strategies.md — Unit and integration testing approaches

• examples.md — Complete working examples

• event-driven-patterns-reference.md — Detailed reference documentation

Constraints and Warnings

• Events published with @TransactionalEventListener only fire after transaction commit

• Avoid publishing large objects in events (memory pressure, serialization issues)

• Be cautious with async event handlers (separate threads, concurrency issues)

• Kafka consumers must handle duplicate messages (implement idempotent processing)

• Event ordering is not guaranteed in distributed systems (design handlers to be order-independent)

• Never perform blocking operations in event listeners on the main transaction thread

• Monitor for event processing backlogs (indicate system capacity issues)

Related Skills

• spring-boot-security-jwt — JWT authentication for secure event publishing

• spring-boot-test-patterns — Testing event-driven applications

• aws-sdk-java-v2-lambda — Event-driven processing with AWS Lambda

• langchain4j-tool-function-calling-patterns — AI-driven event processing