---

name: event-driven-messaging description: > Use when implementing Kafka, RabbitMQ, Pulsar, or JMS producers and consumers in Spring Boot 4. Covers modular starters, event contracts, idempotency, retries, dead letters, and outbox delivery.

Event-Driven Messaging

Design for at-least-once delivery unless the complete system proves stronger semantics.

Dependencies and contracts

• Use the dedicated Boot 4 starter and matching technology test starter.
• Let Boot manage Spring Kafka, AMQP, Pulsar, and Integration versions.
• Publish immutable envelopes containing event ID, type, timestamp, schema version, and payload.
• Treat event schemas as public APIs and evolve them compatibly.
• Do not serialize JPA entities or internal Jackson configuration as contracts.

Producer rules

• Publish only after the originating state is durable.
• Use a transactional outbox when a database write and message must agree.
• Choose a stable aggregate key when per-aggregate ordering matters.
• Configure acknowledgements, delivery timeout, and serialization failure behavior explicitly.

Consumer rules

• Make every handler idempotent with a durable marker or naturally idempotent state transition.
• Commit the state change and idempotency marker in one transaction.
• Retry only transient failures with bounded exponential backoff.
• Route permanent or exhausted failures to a dead-letter destination with diagnostic headers.
• Build replay as an explicit operation with authorization and auditability.

Testing

• Use the Boot 4 technology test starter and Testcontainers for broker integration.
• Test duplicate, reordered, delayed, incompatible, and poison events.
• Verify schema compatibility independently from handler tests.

Examples

• See examples/good-consumer.java, examples/good-kafka.yml, and examples/bad-consumer.java.

Official sources

• Boot 4 messaging starters: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide#starters
• Spring Kafka reference: https://docs.spring.io/spring-kafka/reference/
• Spring AMQP reference: https://docs.spring.io/spring-amqp/reference/

Gotchas

• Agent assumes broker transactions make external side effects exactly once - consumers still need idempotency.
• Agent retries every exception - classify permanent failures before retrying.
• Agent publishes directly after a repository call - use an outbox when atomicity matters.
• Agent uses old Boot 3 transitive dependencies - declare the Boot 4 messaging and test starters.
• Agent sends framework entities as events - publish a stable versioned contract.