跳到主要内容
版本：5.0.1

RabbitMQ Binder 参考指南

DeepSeek V3 中英对照 RabbitMQ Binder Reference Guide

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

用法​

要使用 RabbitMQ 绑定器，你可以通过以下 Maven 坐标将其添加到你的 Spring Cloud Stream 应用程序中：

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

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

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

RabbitMQ Binder 概述​

以下简化示意图展示了 RabbitMQ 绑定器的工作原理：

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

通过使用可选的 autoBindDlq 选项，你可以配置 binder 来创建和配置死信队列（DLQ）（以及死信交换器 DLX 和路由基础设施）。默认情况下，死信队列的名称是目标名称，并附加 .dlq。如果启用了重试（maxAttempts > 1），则在重试耗尽后，失败的消息将被传递到 DLQ。如果禁用了重试（maxAttempts = 1），你应该将 requeueRejected 设置为 false（默认值），以便将失败的消息路由到 DLQ，而不是重新排队。此外，republishToDlq 会导致 binder 将失败的消息发布到 DLQ（而不是拒绝它）。此功能允许在消息的 header 中添加额外的信息（例如 x-exception-stacktrace header 中的堆栈跟踪）。有关截断堆栈跟踪的信息，请参阅 frameMaxHeadroom 属性。此选项不需要启用重试。你可以在仅尝试一次后重新发布失败的消息。从版本 1.2 开始，你可以配置重新发布消息的传递模式。请参阅 republishDeliveryMode 属性。

如果流监听器抛出 ImmediateAcknowledgeAmqpException，则死信队列（DLQ）会被绕过，消息直接被丢弃。从版本 2.1 开始，无论 republishToDlq 的设置如何，此行为均成立；在此之前，仅当 republishToDlq 为 false 时才如此。

important

将 requeueRejected 设置为 true（同时 republishToDlq=false）会导致消息被重新排队并持续重新投递，这通常不是您想要的结果，除非失败的原因是暂时的。通常，您应该通过在绑定器中设置 maxAttempts 大于 1 或将 republishToDlq 设置为 true 来启用重试机制。

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

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

该框架未提供任何标准机制来处理死信消息（或将其重新路由回主队列）。有关一些选项，请参阅死信队列处理。

备注

在 Spring Cloud Stream 应用程序中使用多个 RabbitMQ 绑定器时，禁用 'RabbitAutoConfiguration' 非常重要，以避免来自 RabbitAutoConfiguration 的相同配置被应用到两个绑定器上。你可以使用 @SpringBootApplication 注解来排除该类。

从 2.0 版本开始，RabbitMessageChannelBinder 将 RabbitTemplate.userPublisherConnection 属性设置为 true，这样非事务性生产者可以避免在消费者上发生死锁。如果由于代理上的内存警报导致缓存连接被阻塞，就可能发生这种情况。

备注

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

配置选项​

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

有关通用绑定配置选项和属性，请参阅 Spring Cloud Stream 核心文档。

章节总结​

📄️使用现有队列/交换机

默认情况下，绑定器会自动创建一个主题交换机，其名称由目标绑定属性 \<prefix>\<destination> 的值派生而来。如果未提供目标，则默认为绑定名称。当绑定消费者时，将自动创建一个队列，其名称为 \<prefix>\<destination>.\<group>（如果指定了组绑定属性），或者在没有组时创建一个匿名的、自动删除的队列。该队列将使用“匹配所有”的通配符路由键（#）绑定到交换机（对于非分区绑定），或者使用 \<destination>-\<instanceIndex>（对于分区绑定）。默认情况下，前缀为空字符串。如果输出绑定指定了 requiredGroups，将为每个组创建一个队列/绑定。