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