Messaging & Event Streaming
RabbitMQ with Spring AMQP and Spring Boot: RabbitTemplate, @RabbitListener and Retries
Intermediate7 min readUpdated
Spring AMQP wraps the RabbitMQ Java client in the abstractions Spring developers expect: a template for publishing, annotated listener methods for consuming, and beans that declare the broker topology on startup. After this guide you will be able to build a Spring Boot 3 service that publishes JSON events with confirms, consumes them concurrently with manual acknowledgements, retries transient failures, dead-letters poison messages, and tests it all against a real broker with Testcontainers.
What you will learn
- Add Spring AMQP to a Spring Boot 3 project and configure the connection through properties
- Declare exchanges, queues and bindings as beans so RabbitAdmin creates them on startup
- Publish JSON messages with RabbitTemplate and react to publisher confirms and returns
- Consume with @RabbitListener using concurrency, prefetch and manual acknowledgement
- Configure retry with backoff and dead-letter routing for failed messages
- Implement request-reply and write integration tests with Testcontainers
The RabbitMQ Java client gives you channels, byte arrays and callbacks. Spring AMQP gives you a RabbitTemplate that publishes objects, a @RabbitListener annotation that turns a method into a scalable consumer, and a RabbitAdmin that creates the exchanges and queues your beans describe. Spring Boot adds auto-configuration and properties on top. The result is a service in which the messaging code is a few dozen lines, and this guide shows those lines together with the settings that make them safe under load. It targets Spring Boot 3.x with Spring AMQP 3.x; the ideas carry over to Spring AMQP 4 unchanged, although a few class names differ.
Setup and connection
One starter brings in Spring AMQP and the RabbitMQ client:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-amqp</artifactId>
</dependency>
Boot creates a CachingConnectionFactory — a single connection whose channels are pooled and reused across threads, which is the correct pattern for AMQP — and configures it from properties:
spring:
rabbitmq:
addresses: amqps://rabbit-1.internal:5671,amqps://rabbit-2.internal:5671 # cluster nodes, TLS
username: orders
password: ${RABBITMQ_PASSWORD}
virtual-host: shop
connection-timeout: 5s
publisher-confirm-type: correlated # enable confirms with a CorrelationData callback
publisher-returns: true # get unroutable messages back
template:
mandatory: true # required for returns to fire
retry:
enabled: true # retry a failed publish (broker unavailable)
max-attempts: 3
initial-interval: 500ms
listener:
simple:
acknowledge-mode: auto # ack on success, nack on exception
prefetch: 20
concurrency: 2
max-concurrency: 8
default-requeue-rejected: false # rejected messages go to the DLX, not back to the queue
The addresses list gives the client several nodes to try; the caching factory reconnects to the next one when a node goes away, and consumers re-subscribe automatically. Everything else in this file is explained as it comes up.
Declaring the topology as beans
Spring AMQP models exchanges, queues and bindings as beans. On the first connection, RabbitAdmin (auto-configured by Boot) declares every Declarable in the context, and it redeclares them after a reconnection. The declarations are idempotent, so several instances of the service can start in any order.
@Configuration
class OrdersTopology {
static final String EXCHANGE = "orders";
static final String QUEUE = "fulfilment";
static final String DLX = "orders.dlx";
@Bean TopicExchange ordersExchange() { return ExchangeBuilder.topicExchange(EXCHANGE).durable(true).build(); }
@Bean DirectExchange ordersDlx() { return ExchangeBuilder.directExchange(DLX).durable(true).build(); }
@Bean Queue fulfilmentQueue() {
return QueueBuilder.durable(QUEUE)
.quorum() // x-queue-type=quorum
.deadLetterExchange(DLX)
.deadLetterRoutingKey(QUEUE)
.deliveryLimit(5) // quorum queues: dead-letter after 5 redeliveries
.build();
}
@Bean Queue fulfilmentDlq() { return QueueBuilder.durable(QUEUE + ".dlq").quorum().build(); }
@Bean Binding fulfilmentBinding() {
return BindingBuilder.bind(fulfilmentQueue()).to(ordersExchange()).with("order.*.placed");
}
@Bean Binding fulfilmentDlqBinding() {
return BindingBuilder.bind(fulfilmentDlq()).to(ordersDlx()).with(QUEUE);
}
}
Two habits keep this manageable as a service grows. Put the names in constants (or a @ConfigurationProperties class) so publishers, listeners and tests agree on them, and group related declarations in a Declarables bean when you have many, instead of a bean per binding. Remember that queue arguments are immutable: if you later change deliveryLimit on a queue that already exists, RabbitMQ refuses the declaration with a PRECONDITION_FAILED error and the listener will not start. Delete the queue or express the setting as a policy.
Publishing with RabbitTemplate
RabbitTemplate.convertAndSend serialises an object with the configured MessageConverter, sets the content type, and publishes it to an exchange with a routing key. By default the converter is SimpleMessageConverter, which handles strings, byte arrays and Java serialisation; declare a JSON converter and Boot injects it into both the template and the listener container factory:
@Bean
MessageConverter jsonMessageConverter() {
return new Jackson2JsonMessageConverter(); // Spring AMQP 3.x; JacksonJsonMessageConverter in 4.x
}
@Service
class OrderEventPublisher {
private final RabbitTemplate rabbit;
OrderEventPublisher(RabbitTemplate rabbit) {
this.rabbit = rabbit;
rabbit.setConfirmCallback((correlation, ack, cause) -> {
if (!ack) log.error("broker rejected {}: {}", correlation != null ? correlation.getId() : "?", cause);
});
rabbit.setReturnsCallback(returned ->
log.error("unroutable message to {} with key {}: {}",
returned.getExchange(), returned.getRoutingKey(), returned.getReplyText()));
}
public void orderPlaced(OrderPlaced event) {
rabbit.convertAndSend(OrdersTopology.EXCHANGE, "order." + event.region() + ".placed", event,
message -> {
message.getMessageProperties().setMessageId(event.orderId()); // for consumer-side de-duplication
message.getMessageProperties().setHeader("schemaVersion", 2);
return message;
},
new CorrelationData(event.orderId()));
}
}
With publisher-confirm-type: correlated, the broker confirms or rejects each publish and the template calls your ConfirmCallback with the CorrelationData you passed. A nack means the broker could not take responsibility for the message — a node was lost mid-publish, or a quorum queue had no majority — and the right reaction is to retry or record the failure, not to log and forget. The returns callback fires when mandatory is true and the routing key matched no binding, which is the only way to notice a typo in a routing key.
The MessagePostProcessor lambda is where headers, message identifiers, priorities and expirations are set. Persistent delivery mode is the template's default.
Consuming with @RabbitListener
A @RabbitListener method becomes a consumer backed by a listener container. Boot creates a SimpleMessageListenerContainer per annotation from the spring.rabbitmq.listener.simple.* properties; the payload is converted with the same JSON converter, and headers are injectable.
@Component
class FulfilmentListener {
@RabbitListener(queues = OrdersTopology.QUEUE, concurrency = "2-8")
public void onOrderPlaced(OrderPlaced event,
@Header(AmqpHeaders.MESSAGE_ID) String messageId,
@Header(name = "x-delivery-count", required = false) Long deliveryCount) {
if (fulfilments.alreadyProcessed(messageId)) return; // idempotent: duplicates are harmless
fulfilments.fulfil(event); // throwing here → nack → DLX (requeue disabled)
}
}
concurrency = "2-8" starts two consumer threads and scales up to eight while the queue has a backlog. Each thread holds its own channel with the configured prefetch, so eight consumers and a prefetch of 20 can have 160 messages unacknowledged at once — size prefetch with that multiplication in mind.
With acknowledge-mode: auto (the default) the container acknowledges after the method returns and negatively acknowledges when it throws. Because default-requeue-rejected is false in the configuration above, a rejected message goes to the dead-letter exchange rather than back to the front of the queue. To reject one message deliberately regardless of that setting, throw AmqpRejectAndDontRequeueException; to ask for a requeue when a downstream system is briefly unavailable, throw ImmediateRequeueAmqpException.
Manual acknowledgement
Some workloads need to acknowledge at a precise point — after a database commit, or in batches. Switch the container to AcknowledgeMode.MANUAL and inject the channel and delivery tag:
@RabbitListener(queues = OrdersTopology.QUEUE, ackMode = "MANUAL")
public void onOrderPlaced(OrderPlaced event, Channel channel,
@Header(AmqpHeaders.DELIVERY_TAG) long tag) throws IOException {
try {
fulfilments.fulfil(event);
channel.basicAck(tag, false);
} catch (DownstreamUnavailable e) {
channel.basicNack(tag, false, true); // requeue: another instance may succeed
} catch (RuntimeException e) {
channel.basicNack(tag, false, false); // dead-letter it
}
}
The container will not acknowledge on your behalf in manual mode, so a method that forgets to ack leaves the message unacknowledged until the channel closes — and the broker's consumer timeout closes it after thirty minutes with an error.
Declaring the queue on the listener
For small services it is convenient to declare the binding on the annotation itself; RabbitAdmin picks it up like any other declarable:
@RabbitListener(bindings = @QueueBinding(
value = @Queue(value = "notifications", durable = "true",
arguments = @Argument(name = "x-queue-type", value = "quorum")),
exchange = @Exchange(value = "orders", type = ExchangeTypes.TOPIC),
key = "order.#"))
public void notify(OrderPlaced event) { ... }
Retries and dead letters
There are three layers at which a failed message can be retried, and a robust service uses two of them.
| Layer | Mechanism | Good for | Limits |
|---|---|---|---|
| Listener container | Spring Retry interceptor: listener.simple.retry.* properties | Brief transient failures (a timeout on one HTTP call) | Retries happen in memory, blocking the consumer thread; lost on restart |
| Broker | Dead-letter exchange, optionally via a TTL "wait" queue that routes back | Longer delays, survives restarts, visible in the management UI | Requires topology; delivery count must be checked to stop loops |
| Dead-letter queue | A separate listener or manual replay | Poison messages that need a human or a fix | Needs tooling and monitoring |
The container-level retry is a property change:
spring:
rabbitmq:
listener:
simple:
retry:
enabled: true
max-attempts: 4 # the original delivery plus three retries
initial-interval: 1s
multiplier: 2.0 # 1 s, 2 s, 4 s
max-interval: 10s
default-requeue-rejected: false
When the retries are exhausted, the container's MessageRecoverer decides the fate of the message. The default RejectAndDontRequeueRecoverer rejects it without requeue, which sends it to the dead-letter exchange configured on the queue. RepublishMessageRecoverer is an alternative that publishes the message to an exchange of your choice with headers describing the exception and stack trace, which is far more useful when someone later opens the dead-letter queue to understand what went wrong:
@Bean
MessageRecoverer messageRecoverer(RabbitTemplate template) {
return new RepublishMessageRecoverer(template, OrdersTopology.DLX, OrdersTopology.QUEUE);
}
Whatever the mechanism, a dead-letter queue needs an owner: an alert on its depth, a listener that files the failure somewhere visible, and a documented way to replay after the bug is fixed — usually the management UI's move messages feature (with the shovel plugin) or a small admin endpoint that reads the dead-letter queue and republishes.
Request-reply
RabbitTemplate.convertSendAndReceive implements remote-procedure calls over AMQP: it publishes a request, waits for a reply with a matching correlation identifier, and converts the result. By default it uses RabbitMQ's direct reply-to pseudo-queue (amq.rabbitmq.reply-to), which avoids creating a temporary queue per call and is fast enough for interactive use.
PriceQuote quote = rabbit.convertSendAndReceiveAsType(
"pricing", "quote.request", new QuoteRequest("A-100", 3),
new ParameterizedTypeReference<PriceQuote>() {});
On the server side a @RabbitListener method simply returns a value; the container sends it to the request's replyTo with the same correlationId:
@RabbitListener(queues = "pricing.requests")
public PriceQuote quote(QuoteRequest request) {
return pricing.quote(request.sku(), request.quantity());
}
Set spring.rabbitmq.template.reply-timeout (five seconds by default) to something that matches the caller's own timeout, and remember that request-reply reintroduces the temporal coupling messaging was meant to remove: if the pricing service is down, the caller fails after the timeout exactly as an HTTP call would.
Testing against a real broker
Mocking RabbitTemplate tests nothing about routing keys, converters or acknowledgements. Testcontainers starts a real RabbitMQ in Docker, and Boot's @ServiceConnection (3.1+) wires the connection properties without any manual configuration:
@SpringBootTest
@Testcontainers
class FulfilmentFlowTest {
@Container @ServiceConnection
static RabbitMQContainer rabbit = new RabbitMQContainer("rabbitmq:4.0-management");
@Autowired OrderEventPublisher publisher;
@Autowired FulfilmentRepository fulfilments;
@Test
void placedOrderIsFulfilled() {
publisher.orderPlaced(new OrderPlaced("o-1", "eu", 149.90));
Awaitility.await().atMost(Duration.ofSeconds(5))
.untilAsserted(() -> assertThat(fulfilments.find("o-1")).isPresent());
}
}
Because the topology beans declare everything on startup, the test runs against an empty broker with no fixtures. Use the -management image tag when you want to open the UI on the mapped port while debugging a failing test.
Common mistakes
- Missing JSON converter. Listeners receive
byte[]or fail with aClassCastException; publishers send Java-serialised payloads that non-Java consumers cannot read. Declare the converter bean once. - Leaving
default-requeue-rejectedattrue. A listener that throws on a malformed message spins at full speed on the same message forever. Set it tofalseand dead-letter. - Ignoring confirm and return callbacks. Publishes silently vanish on a broker hiccup or a misspelt routing key. Enable
correlatedconfirms,mandatory, and log or retry in the callbacks. - Changing queue arguments on an existing queue.
PRECONDITION_FAILEDon startup. Delete the queue in non-production; use policies in production. - Blocking retry with long intervals. A listener thread sleeping for minutes between retries is a thread you no longer have. Keep container retries short and push long waits to a TTL queue.
- Sharing mutable state across concurrent listener threads.
concurrency = "2-8"means your listener bean is called from eight threads at once; keep it stateless or synchronise properly.
Key takeaways
- Boot's
spring-boot-starter-amqpgives you a caching connection factory, aRabbitTemplate, aRabbitAdminand listener containers configured fromspring.rabbitmq.*properties. - Declare exchanges, queues and bindings as beans; they are created idempotently on the first connection, and quorum queues with a dead-letter exchange should be the default shape.
- Publish with a JSON
MessageConverter, correlated confirms andmandatoryreturns so you know what the broker accepted. @RabbitListenerscales withconcurrency, is bounded by prefetch, and acknowledges automatically on return or rejects on exception; use manual mode only when the acknowledgement point must be precise.- Retry briefly in the container, then dead-letter through the broker; make sure
default-requeue-rejectedisfalseand that someone owns the dead-letter queue. - Test the real flow with Testcontainers and
@ServiceConnection; mocks cannot catch routing or serialisation errors.
Sources and further reading
Frequently asked questions
- Do I have to declare queues in code, or can an administrator create them?
- Either works. Declaring Queue, Exchange and Binding beans makes the application self-contained and lets tests start from an empty broker; RabbitAdmin declares them when the first connection opens, and declaration is idempotent. In environments where developers may not have configure permission, leave the beans out and let operations create the topology with policies and the management API — the listener simply fails to start if the queue is missing, which is what you want.
- Why are my listener methods receiving a byte array instead of my object?
- Because no JSON MessageConverter is configured, so Spring AMQP falls back to the SimpleMessageConverter, which hands over bytes unless the content type is text/plain or the payload is a serialised Java object. Declare a Jackson JSON converter bean; Spring Boot wires it into both RabbitTemplate and the listener container factory automatically.
- Should I use Spring Retry in the listener or a dead-letter queue with TTL?
- Both, for different failures. Listener-level retry with backoff handles short outages of a downstream dependency without leaving the consumer. A dead-letter exchange catches what still fails after retries so it can be inspected and replayed. For long waits between attempts, a TTL queue that dead-letters back to the work queue keeps the consumer free and survives restarts, which in-memory retry does not.
- What does default-requeue-rejected do?
- It decides what happens when a listener throws. With the default of true, the message is requeued and delivered again immediately, which turns a deterministic bug into a tight loop. Set it to false so rejected messages are discarded or dead-lettered, and throw AmqpRejectAndDontRequeueException from the listener when you want to reject one message explicitly regardless of the setting.