Skip to content

rrezartprebreza/spring-boot-skills / skills/spring-boot-4/event-driven-messaging

event-driven-messaging

Verified

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.

FileKindSize
SKILL.mdskill md3.0 KB
agents/openai.yamlconfig207 B
examples/bad-consumer.javaother162 B
examples/good-consumer.javaother1.2 KB
examples/good-kafka.ymlconfig166 B
---
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/

## Verification scope

The workflow fixture compiles good-consumer.java directly and checks duplicate delivery,
concurrent invocation and claim/effect rollback against PostgreSQL. It calls the consumer
directly: broker serialization, listener wiring, offsets, retries and dead-letter delivery
are not covered.
See the [coverage matrix](https://github.com/rrezartprebreza/spring-boot-skills/blob/main/verification/MATRIX.md)
for pinned versions and remaining gaps.

## 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.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall