Spring AMQP声明仲裁队列必须显式调用.quorum()，否则默认创建经典队列；该方法强制启用durable=true、禁用autoDelete和exclusive，并确保RabbitMQ集群≥3节点才能正常运行。
Spring AMQP 声明 Queue 时必须显式调用 .quorum()
spring boot 3.x + spring amqp 3.x 默认声明的队列是经典队列（classic），即使 rabbitmq 集群已就绪、且你期望高可用，@bean queue 不加任何修饰也会创建出非复制队列。这不是 bug，而是设计：仲裁队列需主动启用，避免误用带来的性能代价。
正确方式是使用 QueueBuilder 的 .quorum() 方法 —— 它会自动注入 x-queue-type=quorum 参数，其他参数如持久化、名称等仍可链式设置：
@Bean
public Queue paymentQuorumQueue() {
return QueueBuilder.durable("payment.queue")
.quorum() // ← 关键！不加这行就是 classic 队列
.withArgument("x-max-length", 10000)
.withArgument("x-message-ttl", 600_000)
.build();
}
注意：.quorum() 是语义标记，不是开关；它不接受布尔参数，也不能和 .autoDelete() 或 .exclusive() 共存 —— 仲裁队列强制要求 durable=true、autoDelete=false、exclusive=false，否则声明会失败并抛出 IOException。
为什么不能靠 x-queue-type 参数手动覆盖？
理论上可以在 withArgument("x-queue-type", "quorum") 手动设参数，但 Spring AMQP 在底层做了校验：当检测到 x-queue-type=quorum 但未调用 .quorum() 时，会静默忽略该参数，仍按 classic 创建。这是为了防止配置错位导致行为不可控。
常见错误现象包括：
- 管理界面看到队列类型显示为
classic，哪怕你写了withArgument("x-queue-type", "quorum") - 集群中只在单节点有数据，宕机后消息丢失
- 消费者连上不同节点时收不到消息（因为元数据共享但消息不复制）
根本原因：Spring AMQP 的 QueueBuilder 对仲裁队列做了封装级约束，绕过 .quorum() 就无法触发其内部的队列属性适配逻辑。
搭配 @RabbitListener 自动声明时怎么写？
如果不想单独定义 @Bean Queue，而希望监听器启动时自动声明仲裁队列，必须用 queuesToDeclare 显式传入一个已调用 .quorum() 的 Queue 实例：
@RabbitListener(
queuesToDeclare = @Queue(
name = "order.event.queue",
durable = "true",
autoDelete = "false",
exclusive = "false",
arguments = {
@Argument(name = "x-queue-type", value = "quorum"),
@Argument(name = "x-max-length", value = "5000")
}
)
)
⚠️ 这种写法看似可行，但实际无效 —— @Queue 注解里的 arguments 不参与 QueueBuilder.quorum() 流程，RabbitMQ 服务端收到请求后会拒绝该参数（返回 PRECONDITION_FAILED 错误）。唯一可靠方式是预先声明 Queue Bean，并在 @RabbitListener 中引用：
@Bean
public Queue orderEventQueue() {
return QueueBuilder.durable("order.event.queue").quorum().build();
}
@RabbitListener(queues = "order.event.queue")
public void onOrderEvent(OrderEvent event) { ... }
集群节点数少于 3 时，.quorum() 会怎样？
RabbitMQ 要求仲裁队列至少运行在 3 个节点上才能形成法定人数（quorum），但 Spring AMQP 声明时不会校验集群规模 —— 它只负责发声明请求。真正报错发生在 RabbitMQ 服务端：
- 单节点集群：声明成功，但日志报
quorum queue requires at least 3 cluster nodes，队列实际不可用，所有 publish 操作会卡住或超时 - 双节点集群：同上，Raft 无法选出 leader，队列处于 pending 状态
- 三节点及以上：正常选举 leader，队列状态显示
running，+2 表示两个 follower
所以，.quorum() 本身不保证可用，它只是“申请创建仲裁队列”的动作。是否真能工作，取决于你连接的 RabbitMQ 集群是否满足 Raft 的最小节点数要求（≥3）和网络连通性。上线前务必在管理界面确认队列状态栏显示 quorum 类型和健康 follower 数量。
