RabbitMQ Binder Reference Guide

本指南介绍了 RabbitMQ Spring Cloud Stream Binder 的实现。它包含有关其设计、用法和配置选项的信息，以及有关 Stream Cloud Stream 概念如何映射到 RabbitMQ 特定构造的信息。

This guide describes the RabbitMQ implementation of the Spring Cloud Stream Binder. It contains information about its design, usage and configuration options, as well as information on how the Stream Cloud Stream concepts map into RabbitMQ specific constructs.

Usage

要使用 RabbitMQ 粘合器，你可以使用以下 Maven 坐标将其添加到 Spring Cloud Stream 应用程序：

To use the RabbitMQ binder, you can add it to your Spring Cloud Stream application, by using the following Maven coordinates:

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-stream-binder-rabbit</artifactId>
</dependency>

或者，你可以使用 Spring Cloud Stream RabbitMQ Starter，如下所示：

Alternatively, you can use the Spring Cloud Stream RabbitMQ Starter, as follows:

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-stream-rabbit</artifactId>
</dependency>

RabbitMQ Binder Overview

以下简化图表显示 RabbitMQ 绑定的工作方式：

The following simplified diagram shows how the RabbitMQ binder operates:

默认情况下，RabbitMQ Binder 实现将每个目标映射到 TopicExchange。对于每个消费者组，将 Queue 绑定到该 TopicExchange。每个消费者实例都为其组的 Queue 具有对应的 RabbitMQ Consumer 实例。对于分区生产者和消费者，队列后缀为分区索引，并使用分区索引作为路由键。对于匿名消费者（没有 group 属性的消费者），将使用一个自动删除队列（具有随机唯一名称）。

By default, the RabbitMQ Binder implementation maps each destination to a TopicExchange. For each consumer group, a Queue is bound to that TopicExchange. Each consumer instance has a corresponding RabbitMQ Consumer instance for its group’s Queue. For partitioned producers and consumers, the queues are suffixed with the partition index and use the partition index as the routing key. For anonymous consumers (those with no group property), an auto-delete queue (with a randomized unique name) is used.

通过使用可选的 autoBindDlq 选项，您可以配置绑定程序以创建和配置死信队列 (DLQ)（以及一个死信交换 DLX 和一个路由基础设施）。默认情况下，死信队列的名称是目标的名称，后缀是 .dlq。如果启用了重试（maxAttempts > 1），则在重试用尽之后将失败的消息传递到 DLQ。如果禁用了重试（maxAttempts = 1），则应将 requeueRejected 设置为 false（默认值），以便将失败的消息路由到 DLQ 中，而不是重新加入队列。此外，republishToDlq 会导致绑定程序将失败的消息发布到 DLQ 中（而不是拒绝该消息）。此功能允许向消息的标头中添加附加信息（比如 x-exception-stacktrace 标头中的堆栈跟踪）。参见 frameMaxHeadroom property 了解有关截断堆栈跟踪的信息。此选项不需要启用重试功能。你可以在第一次尝试后重新发布失败的消息。从 1.2 版本开始，您可以配置已重新发布消息的传递模式。参见 republishDeliveryMode property。

By using the optional autoBindDlq option, you can configure the binder to create and configure dead-letter queues (DLQs) (and a dead-letter exchange DLX, as well as routing infrastructure). By default, the dead letter queue has the name of the destination, appended with .dlq. If retry is enabled (maxAttempts > 1), failed messages are delivered to the DLQ after retries are exhausted. If retry is disabled (maxAttempts = 1), you should set requeueRejected to false (the default) so that failed messages are routed to the DLQ, instead of being re-queued. In addition, republishToDlq causes the binder to publish a failed message to the DLQ (instead of rejecting it). This feature lets additional information (such as the stack trace in the x-exception-stacktrace header) be added to the message in headers. See the frameMaxHeadroom property for information about truncated stack traces. This option does not need retry enabled. You can republish a failed message after just one attempt. Starting with version 1.2, you can configure the delivery mode of republished messages. See the republishDeliveryMode property.

如果流侦听器抛出 ImmediateAcknowledgeAmqpException，那么 DLQ 被绕过，消息将被简单地丢弃。从版本 2.1 开始，无论 republishToDlq 的设置如何，此情况都成立；之前，只有当 republishToDlq 为 false 时，情况才成立。

If the stream listener throws an ImmediateAcknowledgeAmqpException, the DLQ is bypassed and the message simply discarded. Starting with version 2.1, this is true regardless of the setting of republishToDlq; previously it was only the case when republishToDlq was false.

将 requeueRejected 设置为 true（使用 republishToDlq=false）会导致消息被重新排队并连续发送，这可能不是您的预期，除非故障原因是瞬态的。通常情况下，您应通过将 maxAttempts 设置为大于 1 或将 republishToDlq 设置为 true 来启用 Binder 中的重试。

Setting requeueRejected to true (with republishToDlq=false ) causes the message to be re-queued and redelivered continually, which is likely not what you want unless the reason for the failure is transient. In general, you should enable retry within the binder by setting maxAttempts to greater than one or by setting republishToDlq to true.

从版本 3.1.2 开始，如果消费者标记为 transacted，则发布到 DLQ 将参与事务。如果出于某种原因发布失败（例如，如果用户无权发布到死信交换），则此操作允许事务回滚。此外，如果连接工厂配置为发布者确认或返回，则发布到 DLQ 的操作将等待确认并检查返回的消息。如果收到负面确认或返回的消息，则绑定将抛出 AmqpRejectAndDontRequeueException，允许代理处理发布到 DLQ 的操作，就像 republishToDlq 属性为 false 一样。

Starting with version 3.1.2, if the consumer is marked as transacted, publishing to the DLQ will participate in the transaction. This allows the transaction to roll back if the publishing fails for some reason (for example, if the user is not authorized to publish to the dead letter exchange). In addition, if the connection factory is configured for publisher confirms or returns, the publication to the DLQ will wait for the confirmation and check for a returned message. If a negative acknowledgment or returned message is received, the binder will throw an AmqpRejectAndDontRequeueException, allowing the broker to take care of publishing to the DLQ as if the republishToDlq property is false.

有关这些属性的更多信息，请参阅 RabbitMQ Binder Properties。

See RabbitMQ Binder Properties for more information about these properties.

该框架不提供任何标准机制来使用死信消息（或将其重新路由回主队列）。Dead-Letter Queue Processing中描述了一些选项。

The framework does not provide any standard mechanism to consume dead-letter messages (or to re-route them back to the primary queue). Some options are described in Dead-Letter Queue Processing.

如果在一个 Spring Cloud Stream 应用程序中使用了多个 RabbitMQ 绑定，则禁用“RabbitAutoConfiguration”非常重要，以避免 RabbitAutoConfiguration 中的同一配置被应用到两个绑定。您可以通过使用 @SpringBootApplication 注释来排除该类。

When multiple RabbitMQ binders are used in a Spring Cloud Stream application, it is important to disable 'RabbitAutoConfiguration' to avoid the same configuration from RabbitAutoConfiguration being applied to the two binders. You can exclude the class by using the @SpringBootApplication annotation.

从 2.0 版本开始，RabbitMessageChannelBinder 将 RabbitTemplate.userPublisherConnection 属性设置为 true，以便非事务性生产者避免消费者出现死锁。如果缓存的连接因为代理程序上的 memory alarm 而阻塞，就有可能出现死锁。

Starting with version 2.0, the RabbitMessageChannelBinder sets the RabbitTemplate.userPublisherConnection property to true so that the non-transactional producers avoid deadlocks on consumers, which can happen if cached connections are blocked because of a memory alarm on the broker.

目前，仅消息驱动的使用者支持 multiplex 使用者（一个使用者监听多个队列）；轮询使用者只能从一个队列中检索消息。

Currently, a multiplex consumer (a single consumer listening to multiple queues) is only supported for message-driven consumers; polled consumers can only retrieve messages from a single queue.

Configuration Options

本节包含特定于 RabbitMQ Binder 和绑定通道的设置。

This section contains settings specific to the RabbitMQ Binder and bound channels.

有关常规绑定配置选项和属性，请参见 Spring Cloud Stream core documentation。

For general binding configuration options and properties, see the Spring Cloud Stream core documentation.