消息监听器容器配置

配置 SimpleMessageListenerContainer (SMLC) 和 DirectMessageListenerContainer (DMLC) 有相当多的选项，涉及到事务和质量保证，其中一些选项之间会相互作用。适用于 SMLC、DMLC 或 StreamListenerContainer (StLC) 的属性（参见使用 RabbitMQ Stream 插件）在相应的列中用勾号表示。有关选择哪种容器适用于您的应用程序的信息，请参见选择容器。

下表显示了消息监听器容器的属性名称及其在使用命名空间配置 <rabbit:listener-container/> 时的等效属性名称（括号中）。该元素的 type 属性可以是 simple（默认）或 direct，分别指定 SMLC 或 DMLC。命名空间未公开某些属性。这些属性的属性名显示为 N/A。

属性 (Attribute) 描述 SMLC DMLC StLC

ackTimeout
(N/A)

当设置 messagesPerAck 时，此超时用于替代发送确认。当有新消息到达时，将未确认消息的数量与 messagesPerAck 进行比较，并将自上次确认以来的时间与此值进行比较。如果任一条件为 true，则确认消息。当没有新消息到达且存在未确认消息时，此超时是近似的，因为条件仅在每个 monitorInterval 期间检查一次。另请参阅此表中的 messagesPerAck 和 monitorInterval。

acknowledgeMode
(acknowledge)

NONE: 不发送确认（与 channelTransacted=true 不兼容）。RabbitMQ 将其称为“autoack”，因为代理假设所有消息在消费者未执行任何操作的情况下都被确认。
MANUAL: 监听器必须通过调用 Channel.basicAck() 手动确认所有消息。
AUTO: 容器自动确认消息，除非 MessageListener 抛出异常。请注意，acknowledgeMode 是 channelTransacted 的补充——如果通道是事务性的，代理除了确认之外还需要提交通知。这是默认模式。另请参阅 batchSize。

adviceChain
(advice-chain)

应用于监听器执行的 AOP Advice 数组。可用于应用额外的横切关注点，例如在代理死亡时自动重试。请注意，只要代理仍然存活，CachingConnectionFactory 即可处理 AMQP 错误后的简单重连。

afterReceivePostProcessors
(N/A)

在调用监听器之前调用的 MessagePostProcessor 实例数组。后处理器可以实现 PriorityOrdered 或 Ordered。数组按顺序排序，未排序的成员最后调用。如果后处理器返回 null，则消息将被丢弃（并在适当情况下被确认）。

alwaysRequeueWithTxManagerRollback
(N/A)

当配置了事务管理器时，设置为 true 表示在回滚时总是重新入队消息。

autoDeclare
(auto-declare)

当设置为 true（默认）时，如果容器在启动期间检测到其至少一个队列丢失，则使用 RabbitAdmin 重新声明所有 AMQP 对象（队列、交换器、绑定）。这可能是因为队列是 auto-delete 队列或已过期队列，但如果队列因任何原因丢失，重新声明仍会进行。要禁用此行为，请将此属性设置为 false。请注意，如果容器的所有队列都丢失，则容器将无法启动。

在版本 1.6 之前，如果上下文中存在多个 admin，容器将随机选择一个。如果没有 admin，它将在内部创建一个。无论哪种情况，这都可能导致意外结果。从版本 1.6 开始，为了使 autoDeclare 工作，上下文中必须只有一个 RabbitAdmin，或者必须使用 rabbitAdmin 属性在容器上配置特定实例的引用。

autoStartup
(auto-startup)

指示容器是否应随 ApplicationContext 一起启动的标志（作为 SmartLifecycle 回调的一部分，这发生在所有 bean 初始化之后）。默认为 true，但如果您的代理在启动时可能不可用，您可以将其设置为 false，然后在您知道代理准备好时手动调用 start()。

batchSize
(transaction-size) (batch-size)

当与设置为 AUTO 的 acknowledgeMode 一起使用时，容器会尝试处理达到此数量的消息，然后发送确认（等待每条消息的时间不超过接收超时设置）。这也是事务性通道提交的时候。如果 prefetchCount 小于 batchSize，它将增加到匹配 batchSize。

batchingStrategy
(N/A)

用于解批量消息的策略。默认是 SimpleDebatchingStrategy。参见批量发送和带有批量处理的 @RabbitListener。

channelTransacted
(channel-transacted)

布尔标志，指示所有消息都应在事务中确认（手动或自动）。

concurrency
(N/A)

m-n 每个监听器并发消费者的范围（最小值、最大值）。如果只提供 n，则 n 是固定数量的消费者。参见监听器并发。

concurrentConsumers
(concurrency)

每个监听器最初启动的并发消费者数量。参见监听器并发。对于 StLC，并发性通过重载的 superStream 方法控制；参见使用单个活跃消费者消费超级流。

connectionFactory
(connection-factory)

对 ConnectionFactory 的引用。使用 XML 命名空间配置时，默认引用的 bean 名称是 rabbitConnectionFactory。

consecutiveActiveTrigger
(min-consecutive-active)

消费者在考虑启动新消费者时，连续接收到消息且未发生接收超时的最小数量。也受 'batchSize' 影响。参见监听器并发。默认值：10。

consecutiveIdleTrigger
(min-consecutive-idle)

消费者在考虑停止消费者之前必须经历的最小接收超时次数。也受 'batchSize' 影响。参见监听器并发。默认值：10。

consumerBatchEnabled
(batch-enabled)

如果 MessageListener 支持，将其设置为 true 可启用对离散消息的批处理，最多可达 batchSize；如果在 receiveTimeout 或收集批量消息的时间超过 batchReceiveTimeout 之前没有新消息到达，则会发送部分批次。当此项为 false 时，仅支持由生产者创建的批次；参见批量发送。

consumerCustomizer
(N/A)

一个 ConsumerCustomizer bean，用于修改容器创建的流消费者。

consumerStartTimeout
(N/A)

等待消费者线程启动的时间（毫秒）。如果此时间过去，将写入错误日志。一个可能发生的情况是，配置的 taskExecutor 没有足够的线程来支持容器的 concurrentConsumers。

参见线程与异步消费者。默认值：60000（一分钟）。

consumerTagStrategy
(consumer-tag-strategy)

设置 ConsumerTagStrategy 的实现，从而能够为每个消费者创建（唯一）标签。

consumersPerQueue
(consumers-per-queue)

为每个配置的队列创建的消费者数量。参见监听器并发。

consumeDelay
(N/A)

当使用 RabbitMQ 分片插件并设置 concurrentConsumers > 1 时，可能存在一个竞态条件，导致消费者无法均匀分布到分片上。使用此属性可在消费者启动之间添加一个小的延迟，以避免此竞态条件。您应通过实验确定适合您环境的延迟值。

debatchingEnabled
(N/A)

当为 true 时，监听器容器将解批量处理后的消息，并调用监听器处理批次中的每条消息。从版本 2.2.7 开始，如果监听器是 BatchMessageListener 或 ChannelAwareBatchMessageListener，生产者创建的批次将作为 List<Message> 解批量。否则，批次中的消息将逐个呈现。默认值为 true。参见批量发送和带有批量处理的 @RabbitListener。

declarationRetries
(declaration-retries)

被动队列声明失败时的重试次数。被动队列声明发生在消费者启动时，或在消费多个队列时，当并非所有队列在初始化期间都可用时。如果在重试耗尽后，所有配置的队列都无法被被动声明（无论出于何种原因），容器的行为由 missingQueuesFatal 属性控制（前面已描述）。默认值：三次重试（总共四次尝试）。

defaultRequeueRejected
(requeue-rejected)

确定因监听器抛出异常而被拒绝的消息是否应重新入队。默认值：true。

errorHandler
(error-handler)

对 ErrorHandler 策略的引用，用于处理 MessageListener 执行期间可能发生的任何未捕获异常。默认值：ConditionalRejectingErrorHandler

exclusive
(exclusive)

确定此容器中的单个消费者是否对队列具有独占访问权。当此项为 true 时，容器的并发数必须为 1。如果另一个消费者具有独占访问权，容器会根据 recovery-interval 或 recovery-back-off 尝试恢复消费者。使用命名空间时，此属性出现在 <rabbit:listener/> 元素及其队列名称旁边。默认值：false。

exclusiveConsumerExceptionLogger
(N/A)

当独占消费者无法获得队列访问权时使用的异常记录器。默认情况下，此日志级别为 WARN。

failedDeclarationRetryInterval
(failed-declaration -retry-interval)

被动队列声明重试尝试之间的间隔。被动队列声明发生在消费者启动时，或在消费多个队列时，当并非所有队列在初始化期间都可用时。默认值：5000（五秒）。

forceCloseChannel
(N/A)

如果消费者在 shutdownTimeout 内没有响应关闭请求，并且此属性为 true，则通道将被关闭，导致任何未确认的消息被重新入队。自 2.0 版本以来，默认值为 true。您可以将其设置为 false 以恢复到之前的行为。

forceStop
(N/A)

设置为 true 以在当前记录处理完成后停止（当容器停止时）；这将导致所有预取的消息被重新入队。默认情况下，容器会取消消费者并在停止之前处理所有预取的消息。自版本 2.4.14、3.0.6 以来，默认值为 false。

globalQos
(global-qos)

当为 true 时，prefetchCount 将全局应用于通道，而不是应用于通道上的每个消费者。更多信息请参见 basicQos.global。

(group)

此属性仅在使用命名空间时可用。指定后，将注册一个名为该值的 Collection<MessageListenerContainer> 类型的 bean，并且每个 <listener/> 元素的容器将被添加到集合中。例如，这允许通过遍历集合来启动和停止容器组。如果多个 <listener-container/> 元素具有相同的 group 值，则集合中的容器将构成所有指定容器的聚合。

idleEventInterval
(idle-event-interval)

参见检测空闲异步消费者。

javaLangErrorHandler
(N/A)

一个 AbstractMessageListenerContainer.JavaLangErrorHandler 实现，当容器线程捕获到 Error 时被调用。默认实现调用 System.exit(99)；要恢复到之前的行为（不做任何事情），请添加一个无操作处理程序。

maxConcurrentConsumers
(max-concurrency)

按需启动的最大并发消费者数量。必须大于或等于 'concurrentConsumers'。参见监听器并发。

messagesPerAck
(N/A)

每次确认之间接收的消息数量。使用此项可减少发送到代理的确认数量（代价是增加消息被重新投递的可能性）。通常，仅应在高流量的监听器容器上设置此属性。如果设置了此项并且消息被拒绝（抛出异常），则待处理的确认将被确认，并且失败的消息将被拒绝。不允许与事务性通道一起使用。如果 prefetchCount 小于 messagesPerAck，它将被增加到匹配 messagesPerAck。默认值：每条消息都确认。另请参阅此表中的 ackTimeout。

mismatchedQueuesFatal
(mismatched-queues-fatal)

当容器启动时，如果此属性为 true（默认值：false），容器会检查上下文中声明的所有队列是否与代理上已存在的队列兼容。如果存在不匹配的属性（例如 auto-delete）或参数（例如 x-message-ttl），则容器（和应用程序上下文）将因致命异常而无法启动。

如果在恢复期间检测到问题（例如，连接丢失后），容器将停止。

应用程序上下文中必须有一个唯一的 RabbitAdmin（或一个使用 rabbitAdmin 属性在容器上专门配置的实例）。否则，此属性必须为 false。

如果在初始启动期间代理不可用，容器会启动并在建立连接时检查条件。

检查针对上下文中所有队列进行，而不仅仅是特定监听器配置使用的队列。如果您希望将检查仅限于容器使用的队列，则应为该容器配置一个单独的 RabbitAdmin，并使用 rabbitAdmin 属性提供其引用。更多信息请参见条件声明。

在启动带有 @Lazy 标记的 bean 中包含 @RabbitListener 的容器时，会禁用不匹配队列参数的检测。这是为了避免可能发生的死锁，这会延迟此类容器的启动长达 60 秒。使用延迟监听器 bean 的应用程序应在获取延迟 bean 的引用之前检查队列参数。

missingQueuesFatal
(missing-queues-fatal)

当设置为 true（默认值）时，如果代理上配置的队列均不可用，则视为致命错误。这将导致应用程序上下文在启动期间初始化失败。此外，当队列在容器运行时被删除时，默认情况下，消费者会尝试连接队列三次（间隔五秒），如果这些尝试失败，则停止容器。

这在之前的版本中无法配置。

当设置为 false 时，在尝试三次后，容器将进入恢复模式，就像其他问题（如代理宕机）一样。容器会根据 recoveryInterval 属性尝试恢复。在每次恢复尝试期间，每个消费者将再次尝试被动声明队列四次，间隔五秒。这个过程会无限期持续。

您还可以使用属性 bean 为所有容器全局设置该属性，如下所示：

<util:properties
        id="spring.amqp.global.properties">
    <prop key="mlc.missing.queues.fatal">
        false
    </prop>
</util:properties>

此全局属性不会应用于任何已设置显式 missingQueuesFatal 属性的容器。

默认的重试属性（三次重试，间隔五秒）可以通过设置以下属性进行覆盖。

在启动带有 @Lazy 标记的 bean 中包含 @RabbitListener 的容器时，会禁用丢失队列的检测。这是为了避免可能发生的死锁，这会延迟此类容器的启动长达 60 秒。使用延迟监听器 bean 的应用程序应在获取延迟 bean 的引用之前检查队列。

monitorInterval
(monitor-interval)

对于 DMLC，会在此间隔内调度一个任务来监控消费者的状态并恢复任何失败的消费者。

noLocal
(N/A)

设置为 true 可禁用服务器向在同一通道连接上发布的消费者发送消息。

phase
(phase)

当 autoStartup 为 true 时，此容器应在其中启动和停止的生命周期阶段。值越低，容器启动得越早，停止得越晚。默认值为 Integer.MAX_VALUE，表示容器尽可能晚地启动，尽可能早地停止。

possibleAuthenticationFailureFatal
(possible-authentication-failure-fatal)

当设置为 true（SMLC 的默认值）时，如果在连接期间抛出 PossibleAuthenticationFailureException，则视为致命错误。这将导致应用程序上下文在启动期间初始化失败（如果容器配置为自动启动）。

自 *版本 2.0* 开始。

DirectMessageListenerContainer

当设置为 false（默认值）时，每个消费者将根据 monitorInterval 尝试重新连接。

SimpleMessageListenerContainer

当设置为 false 时，在尝试 3 次后，容器将进入恢复模式，就像其他问题（如代理宕机）一样。容器将根据 recoveryInterval 属性尝试恢复。在每次恢复尝试期间，每个消费者将再次尝试启动 4 次。这个过程将无限期持续。

您还可以使用属性 bean 为所有容器全局设置该属性，如下所示：

<util:properties
    id="spring.amqp.global.properties">
  <prop
    key="mlc.possible.authentication.failure.fatal">
     false
  </prop>
</util:properties>

此全局属性不会应用于任何已设置显式 missingQueuesFatal 属性的容器。

默认的重试属性（3 次重试，间隔 5 秒）可以使用此后的属性进行覆盖。

prefetchCount
(prefetch)

每个消费者可未确认的最大消息数量。此值越高，消息投递速度越快，但非顺序处理的风险也越高。如果 acknowledgeMode 为 NONE 则忽略。如果需要，它会被增加到匹配 batchSize 或 messagePerAck。自 2.0 版本以来默认为 250。您可以将其设置为 1 以恢复到之前的行为。

在某些情况下，预取值应较低——例如，处理大型消息时，特别是如果处理速度较慢（消息可能在客户端进程中占用大量内存），以及如果需要严格的消息顺序（在这种情况下应将预取值设置回 1）。此外，在低流量消息传递和多个消费者（包括单个监听器容器实例内的并发）的情况下，您可能希望减少预取值以实现消息在消费者之间更均匀的分布。

另请参阅 globalQos。

rabbitAdmin
(admin)

当监听器容器监听至少一个自动删除队列，并且在启动期间发现队列丢失时，容器使用 RabbitAdmin 来声明队列以及任何相关的绑定和交换器。如果此类元素配置为使用条件声明（参见条件声明），则容器必须使用配置了声明这些元素的 admin。在此处指定该 admin。仅在使用自动删除队列和条件声明时才需要。如果您不希望自动删除队列在容器启动之前被声明，请将 admin 上的 auto-startup 设置为 false。默认值为一个 RabbitAdmin，它声明所有非条件元素。

receiveTimeout
(receive-timeout)

等待每条消息的最大时间。如果 acknowledgeMode=NONE，这几乎没有影响——容器会循环请求下一条消息。对于事务性 Channel 和 batchSize > 1 的情况，影响最大，因为这可能导致已消费的消息直到超时过期才被确认。当 consumerBatchEnabled 为 true 时，如果在批次完成之前发生此超时，将发送部分批次。

batchReceiveTimeout
(batch-receive-timeout)

收集批量消息的超时时间（毫秒）。它限制了等待填充 batchSize 的时间。当 batchSize > 1 且收集批量消息的时间大于 batchReceiveTime 时，将发送批次。默认值为 0（无超时）。

recoveryBackOff
(recovery-back-off)

指定当消费者因非致命原因启动失败时，尝试启动消费者之间的间隔使用的 BackOff 策略。默认值为 FixedBackOff，每五秒进行无限次重试。与 recoveryInterval 互斥。

recoveryInterval
(recovery-interval)

确定消费者因非致命原因启动失败时，尝试启动的间隔时间（毫秒）。默认值：5000。与 recoveryBackOff 互斥。

retryDeclarationInterval
(缺少队列重试间隔)

如果在消费者初始化期间配置的队列子集可用，则消费者将开始从这些队列消费。消费者会尝试使用此间隔被动地声明缺少的队列。当此间隔过去后，将再次使用 'declarationRetries' 和 'failedDeclarationRetryInterval'。如果仍有缺少的队列，消费者将再次等待此间隔，然后再次尝试。此过程会无限期地持续下去，直到所有队列都可用。默认值：60000（一分钟）。

shutdownTimeout
(N/A)

当容器关闭时（例如，如果其封闭的 ApplicationContext 被关闭），它会等待正在处理的消息完成，直到达到此限制。默认值为五秒。

startConsumerMinInterval
(最小启动间隔)

按需启动每个新消费者之前必须经过的时间（毫秒）。请参阅监听器并发。默认值：10000（10 秒）。

statefulRetryFatal
WithNullMessageId (不适用)

当使用有状态重试建议时，如果接收到缺少 messageId 属性的消息，默认情况下这被认为是致命的，会导致消费者停止。将其设置为 false 以丢弃（或路由到死信队列）此类消息。

stopConsumerMinInterval
(最小停止间隔)

检测到空闲消费者时，自上次停止消费者以来，再次停止消费者之前必须经过的时间（毫秒）。请参阅监听器并发。默认值：60000（一分钟）。

streamConverter
(N/A)

用于将原生 Stream 消息转换为 Spring AMQP 消息的 StreamMessageConverter。

taskExecutor
(任务执行器)

用于执行监听器调用器的 Spring TaskExecutor（或标准 JDK 1.5+ Executor）引用。默认是一个 SimpleAsyncTaskExecutor，使用内部管理的线程。

taskScheduler
(任务调度器)

使用 DMLC 时，用于在 'monitorInterval' 运行监控任务的调度器。

transactionManager
(事务管理器)

用于监听器操作的外部事务管理器。也与 channelTransacted 互补 — 如果 Channel 带有事务，其事务将与外部事务同步。