消息监听器容器配置

DeepSeek V3 中英对照 Message Listener Container Configuration

配置 SimpleMessageListenerContainer (SMLC) 和 DirectMessageListenerContainer (DMLC) 时，有许多与事务和服务质量相关的选项，其中一些选项会相互影响。适用于 SMLC、DMLC 或 StreamListenerContainer (StLC)（参见 使用 RabbitMQ 流插件）的属性在相应的列中用勾号标记。有关帮助您决定哪种容器适合您的应用程序的信息，请参阅 选择容器。

下表展示了在使用命名空间配置 <rabbit:listener-container/> 时，容器属性名称及其对应的属性名称（括号内）。该元素的 type 属性可以是 simple（默认）或 direct，分别用于指定 SMLC 或 DMLC。某些属性未通过命名空间暴露，这些属性在属性列中标记为 N/A。

表 1. 消息监听器容器的配置选项

属性（Attribute）	描述	SMLC（Single-Machine Learning Compiler）是一种单机学习编译器，它专注于在单个计算节点上进行高效的机器学习模型编译和优化。SMLC 的设计目标是通过自动化的编译技术，将高级机器学习模型转换为底层硬件能够高效执行的代码，从而提升模型的运行效率和性能。SMLC 通常支持多种硬件后端，如 CPU、GPU 和 TPU，并能够根据目标硬件的特点进行针对性的优化。	DMLC（Distributed Machine Learning Community）是一个致力于分布式机器学习的社区。该社区汇集了来自学术界和工业界的研究人员和开发者，共同推动分布式机器学习技术的发展和应用。DMLC 开发了多个开源项目，如 XGBoost、MXNet 和 TVM，这些项目在机器学习和深度学习领域具有广泛的影响力。	StLC
ackTimeout (N/A)	当设置了 messagesPerAck 时，此超时时间将作为发送确认的替代方案。当新消息到达时，未确认的消息计数将与 messagesPerAck 进行比较，并且自上次确认以来的时间也将与此值进行比较。如果任一条件为 true，则确认该消息。当没有新消息到达且存在未确认的消息时，此超时是近似的，因为该条件仅在每次 monitorInterval 时检查。另请参阅本表中的 messagesPerAck 和 monitorInterval。
acknowledgeMode (acknowledge)	- NONE: 不发送确认（与 channelTransacted=true 不兼容）。RabbitMQ 称之为“自动确认”，因为代理假定所有消息都已确认，无需消费者采取任何操作。 - MANUAL: 监听器必须通过调用 Channel.basicAck() 来确认所有消息。 - AUTO: 容器会自动确认消息，除非 MessageListener 抛出异常。请注意，acknowledgeMode 与 channelTransacted 是互补的——如果通道是事务性的，代理除了需要确认外，还需要提交通知。这是默认模式。另请参阅 batchSize。
adviceChain (advice-chain)	应用于监听器执行的 AOP 通知数组。这可以用于应用额外的横切关注点，例如在代理（broker）宕机时自动重试。请注意，只要代理仍然存活，AMQP 错误后的简单重连由 CachingConnectionFactory 处理。
afterReceivePostProcessors (不适用)	一个 MessagePostProcessor 实例数组，这些实例在调用监听器之前被调用。后处理器可以实现 PriorityOrdered 或 Ordered 接口。数组会被排序，未排序的成员会在最后调用。如果后处理器返回 null，消息将被丢弃（并在适当时进行确认）。
alwaysRequeueWithTxManagerRollback (N/A)	设置为 true 以在配置事务管理器时始终在回滚时重新排队消息。
autoDeclare (自动声明)	当设置为 true（默认值）时，容器会使用 RabbitAdmin 重新声明所有 AMQP 对象（队列、交换器、绑定），如果在启动时检测到至少有一个队列缺失，可能是因为它是一个 auto-delete 队列或已过期的队列，但无论队列缺失的原因是什么，都会进行重新声明。要禁用此行为，请将此属性设置为 false。请注意，如果所有队列都缺失，容器将无法启动。 :::note 在 1.6 版本之前，如果上下文中有多个 RabbitAdmin，容器会随机选择一个。如果没有 RabbitAdmin，容器会在内部创建一个。无论哪种情况，都可能导致意外的结果。从 1.6 版本开始，要使 autoDeclare 生效，上下文中必须恰好有一个 RabbitAdmin，或者必须使用 rabbitAdmin 属性在容器上配置对特定实例的引用。 :::		在 1.6 版本之前，如果上下文中存在多个 admin，容器会随机选择一个。如果没有 admin，容器会在内部创建一个。无论哪种情况，都可能导致意外的结果。从 1.6 版本开始，为了使 autoDeclare 正常工作，上下文中必须恰好有一个 RabbitAdmin，或者必须使用 rabbitAdmin 属性在容器上配置对特定实例的引用。
	在 1.6 版本之前，如果上下文中有多个 admin，容器会随机选择一个。如果没有 admin，容器会在内部创建一个。无论是哪种情况，都可能导致意外的结果。从 1.6 版本开始，为了使 autoDeclare 正常工作，上下文中必须只有一个 RabbitAdmin，或者必须使用 rabbitAdmin 属性在容器上配置对特定实例的引用。
autoStartup (自动启动)	用于指示容器是否应在 ApplicationContext 启动时启动的标志（作为 SmartLifecycle 回调的一部分，该回调在所有 bean 初始化完成后发生）。默认值为 true，但如果你的代理在启动时可能不可用，你可以将其设置为 false，并在你知道代理准备就绪时手动调用 start()。
batchSize (事务大小) (批量大小)	当与 acknowledgeMode 设置为 AUTO 一起使用时，容器会尝试在发送确认（ack）之前处理最多这个数量的消息（等待每条消息的时间不超过接收超时设置）。这也是事务性通道提交的时候。如果 prefetchCount 小于 batchSize，则会将其增加到与 batchSize 相匹配。
batchingStrategy (N/A)	在解批处理消息时使用的策略。默认值为 SimpleDebatchingStrategy。请参阅 批处理 和 使用批处理的 @RabbitListener。
channelTransacted (channel-transacted)	布尔标志，用于指示在事务中所有消息都应被确认（无论是手动还是自动）。
并发 (N/A)	m-n The range of concurrent consumers for each listener (min, max). If only n is provided, n is a fixed number of consumers. See Listener Concurrency.
concurrentConsumers (并发)	每个监听器最初启动的并发消费者数量。请参阅监听器并发。对于 StLC，并发性通过重载的 superStream 方法进行控制；请参阅使用单活动消费者消费超级流。
connectionFactory (connection-factory)	对 ConnectionFactory 的引用。当使用 XML 命名空间进行配置时，默认引用的 bean 名称为 rabbitConnectionFactory。
consecutiveActiveTrigger (最小连续激活)	在考虑启动新的消费者时，消费者在没有发生接收超时的情况下接收到的连续消息的最小数量。还受到 batchSize 的影响。请参阅 Listener Concurrency。默认值：10。
consecutiveIdleTrigger (最小连续空闲时间)	消费者在考虑停止之前必须经历的最少接收超时次数。这也受到 batchSize 的影响。请参阅 Listener Concurrency。默认值：10。
consumerBatchEnabled (批量启用)	如果 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 (声明重试次数)	当被动队列声明失败时的重试次数。被动队列声明发生在消费者启动时，或者在从多个队列消费时，初始化期间并非所有队列都可用的情况下。当在重试次数用尽后，配置的队列中没有一个能够被被动声明（无论出于何种原因）时，容器的行为将由前面描述的 missingQueuesFatal 属性控制。默认值：三次重试（总共四次尝试）。
defaultRequeueRejected (requeue-rejected)	确定因监听器抛出异常而被拒绝的消息是否应重新排队。默认值：true。
errorHandler (错误处理程序)	对 ErrorHandler 策略的引用，用于处理在 MessageListener 执行期间可能发生的任何未捕获异常。默认值为：ConditionalRejectingErrorHandler。
独占 (exclusive)	确定此容器中的单个消费者是否对队列具有独占访问权限。当此属性为 true 时，容器的并发度必须为 1。如果其他消费者具有独占访问权限，容器将根据 recovery-interval 或 recovery-back-off 尝试恢复消费者。在使用命名空间时，此属性与队列名称一起出现在 <rabbit:listener/> 元素上。默认值：false。
exclusiveConsumerExceptionLogger (N/A)	当独占消费者无法访问队列时使用的异常记录器。默认情况下，此日志记录在 WARN 级别。
failedDeclarationRetryInterval (失败声明重试间隔)	被动队列声明重试尝试之间的间隔。当消费者启动时，或者当从多个队列消费时，在初始化期间并非所有队列都可用时，会进行被动队列声明。默认值：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。
（组）	此功能仅在使用了命名空间时可用。当指定了该属性时，一个类型为 Collection<MessageListenerContainer> 的 bean 将以该名称注册，并且每个 <listener/> 元素的容器将被添加到该集合中。这允许，例如，通过遍历集合来启动和停止一组容器。如果多个 <listener-container/> 元素具有相同的 group 值，集合中的容器将形成一个包含所有指定容器的聚合。
idleEventInterval (idle-event-interval)	请参阅检测空闲的异步消费者。
javaLangErrorHandler (N/A)	一个 AbstractMessageListenerContainer.JavaLangErrorHandler 实现，当容器线程捕获到 Error 时会被调用。默认实现会调用 System.exit(99)；要恢复到之前的行为（不执行任何操作），可以添加一个无操作的处理程序。
maxConcurrentConsumers (最大并发数)	如果需要，按需启动的最大并发消费者数量。必须大于或等于 concurrentConsumers。请参阅监听器并发性。
messagesPerAck (N/A)	在确认之间接收的消息数量。使用此属性可以减少发送给 broker 的确认次数（代价是增加了消息重新传递的可能性）。通常，你应该只在处理大量消息的监听容器上设置此属性。如果设置了此属性并且消息被拒绝（抛出异常），则待确认的消息会被确认，失败的消息会被拒绝。不允许在事务性通道中使用此属性。如果 prefetchCount 小于 messagesPerAck，则会将其增加到与 messagesPerAck 相匹配。默认值：每条消息都确认。另请参阅本表中的 ackTimeout。
mismatchedQueuesFatal (mismatched-queues-fatal)	当容器启动时，如果该属性为 true（默认值为 false），容器会检查上下文中声明的所有队列是否与代理上已存在的队列兼容。如果存在不匹配的属性（例如 auto-delete）或参数（例如 x-message-ttl），容器（以及应用程序上下文）将无法启动，并抛出致命异常。 如果在恢复期间检测到问题（例如，在连接丢失后），容器将停止运行。 应用程序上下文中必须有一个 RabbitAdmin（或通过 rabbitAdmin 属性在容器上专门配置的一个）。否则，此属性必须设置为 false。 :::note 如果在初始启动期间代理不可用，容器会启动，并在连接建立时检查条件。 ::: :::important 检查是针对上下文中的所有队列进行的，而不仅仅是针对特定监听器配置使用的队列。如果希望将检查限制为仅针对容器使用的队列，应为容器配置一个单独的 RabbitAdmin，并使用 rabbitAdmin 属性提供对其的引用。有关更多信息，请参阅条件声明。 ::: :::important 在为标记为 @Lazy 的 bean 中的 @RabbitListener 启动容器时，不匹配的队列参数检测将被禁用。这是为了避免潜在的死锁，这种死锁可能会延迟此类容器的启动，最多可达 60 秒。使用延迟监听器 bean 的应用程序应在获取延迟 bean 的引用之前检查队列参数。 :::		如果代理在初始启动期间不可用，容器会启动，并在连接建立时检查条件。
	如果在初始启动期间 broker 不可用，容器会启动，并在连接建立时检查条件。
	检查是针对上下文中的所有队列进行的，而不仅仅是针对特定监听器配置使用的队列。如果您希望将检查限制为仅容器使用的队列，您应该为容器配置一个单独的 RabbitAdmin，并使用 rabbitAdmin 属性提供对其的引用。有关更多信息，请参阅条件声明。
	在启动一个标记为 @Lazy 的 bean 中的 @RabbitListener 容器时，队列参数不匹配检测被禁用。这是为了避免潜在的死锁，这种死锁可能会延迟此类容器的启动，最长可达 60 秒。使用延迟监听器 bean 的应用程序应在获取延迟 bean 的引用之前检查队列参数。
missingQueuesFatal (missing-queues-fatal)	当设置为 true（默认值）时，如果代理上没有任何配置的队列可用，则认为是致命的。这会导致应用程序上下文在启动期间无法初始化。此外，当容器运行时队列被删除时，默认情况下，消费者会尝试三次连接到队列（间隔五秒），如果这些尝试失败，则停止容器。

在以前的版本中，这是不可配置的。

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

你也可以使用 properties bean 来为所有容器全局设置该属性，如下所示：

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

xml

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

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

:::重要
在为标记为 @Lazy 的 bean 中的 @RabbitListener 启动容器时，缺失队列检测被禁用。这是为了避免潜在的死锁，这种死锁可能会延迟此类容器的启动长达 60 秒。使用延迟监听器 bean 的应用程序应在获取延迟 bean 的引用之前检查队列。
:::| | 在为标记为 @Lazy 的 bean 中的 @RabbitListener 启动容器时，缺失队列检测被禁用。这是为了避免潜在的死锁问题，这种死锁可能会延迟此类容器的启动，延迟时间最长可达 60 秒。使用延迟监听器 bean 的应用程序在获取对延迟 bean 的引用之前应检查队列。| | | |
| | 在为标记为 @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 次。此过程将无限期继续。

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

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

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

默认的重试属性（3 次重试，间隔 5 秒）可以在设置此属性后使用其他属性进行覆盖。| | | |
|
prefetchCount
(预取)| 每个消费者可以未确认的消息数量。这个值越高，消息传递的速度就越快，但非顺序处理的风险也越高。如果 acknowledgeMode 为 NONE，则忽略此设置。如有必要，此值会增加以匹配 batchSize 或 messagePerAck。自 2.0 版本以来，默认值为 250。你可以将其设置为 1 以恢复到之前的行为。

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

另请参阅 globalQos。| | 在某些场景下，prefetch 值应该设置得较低 —— 例如，处理大消息时，尤其是当处理速度较慢时（消息可能会在客户端进程中累积占用大量内存），以及当需要严格的消息顺序时（在这种情况下，prefetch 值应该设置为 1）。此外，在消息量较低且存在多个消费者（包括单个监听器容器实例内的并发）的情况下，你可能希望降低 prefetch 值，以便在消费者之间更均匀地分配消息。| | | |
| | 在某些情况下，预取值（prefetch value）应该设置得较低——例如，处理大消息时，尤其是当处理速度较慢时（消息可能会在客户端进程中累积占用大量内存），以及当需要严格的消息顺序时（在这种情况下，预取值应设置为 1）。此外，在消息量较低且存在多个消费者（包括单个监听器容器实例内的并发）的情况下，您可能希望降低预取值，以便在消费者之间更均匀地分配消息。 |
|
rabbitAdmin
(admin)| 当监听器容器监听至少一个自动删除队列，并且在启动时发现该队列丢失时，容器会使用 RabbitAdmin 来声明该队列以及任何相关的绑定和交换。如果这些元素配置为使用条件声明（参见条件声明），则容器必须使用已配置的管理员来声明这些元素。请在此处指定该管理员。仅在将条件声明与自动删除队列一起使用时才需要此操作。如果您不希望自动删除队列在容器启动之前被声明，请在管理员上将 auto-startup 设置为 false。默认情况下，使用一个 RabbitAdmin 来声明所有非条件元素。| | | |
|
receiveTimeout
(接收超时)| 每次等待消息的最大时间。如果 acknowledgeMode=NONE，这几乎没有影响 —— 容器会循环并请求下一条消息。它对具有 batchSize > 1 的事务性 Channel 影响最大，因为它可能导致已消费的消息在超时到期之前不会被确认。当 consumerBatchEnabled 为 true 时，如果此超时发生在批次完成之前，将传递部分批次。| | | |
|
batchReceiveTimeout
(batch-receive-timeout)| 用于收集批量消息的超时时间（以毫秒为单位）。它限制了等待填满 batchSize 的时间。当 batchSize > 1 且收集批量消息的时间超过 batchReceiveTime 时，将交付批量消息。默认值为 0（无超时）。| | | |
|
recoveryBackOff
(recovery-back-off)| 指定在消费者因非致命原因启动失败时，重试启动之间的间隔时间的 BackOff。默认值为 FixedBackOff，即每五秒重试一次，且重试次数不限。与 recoveryInterval 互斥。| | | |
|
recoveryInterval
(恢复间隔)| 确定在由于非致命原因导致消费者启动失败时，两次启动尝试之间的时间间隔（以毫秒为单位）。默认值：5000。与 recoveryBackOff 互斥。| | | |
|
retryDeclarationInterval
(缺失队列重试间隔)| 如果在消费者初始化期间配置的队列子集可用，消费者将从这些队列开始消费。消费者会尝试使用此间隔被动声明缺失的队列。当此间隔过去后，将再次使用 declarationRetries 和 failedDeclarationRetryInterval。如果仍然存在缺失的队列，消费者将再次等待此间隔后重试。此过程将无限期继续，直到所有队列都可用。默认值：60000（一分钟）。| | | |
|
shutdownTimeout
(不适用)| 当一个容器关闭时（例如，如果其包含的 ApplicationContext 被关闭），它会等待正在处理的消息完成，直到达到此限制。默认值为五秒。| | | |
|
startConsumerMinInterval
(最小启动间隔)| 在每个新消费者按需启动之前必须经过的毫秒时间。请参阅监听器并发。默认值：10000（10 秒）。| | | |
|
statefulRetryFatal
WithNullMessageId (N/A)| 在使用有状态的重试建议时，如果接收到缺少 messageId 属性的消息，默认情况下这会被视为消费者的致命错误（消费者会停止）。将此设置为 false 以丢弃（或路由到死信队列）此类消息。| | | |
|
stopConsumerMinInterval
(最小停止间隔)| 在检测到空闲消费者时，自上一个消费者停止后必须经过的毫秒数，然后才能停止消费者。请参阅监听器并发。默认值：60000（一分钟）。| | | |
|
streamConverter
(N/A)| 一个 StreamMessageConverter，用于将原生 Stream 消息转换为 Spring AMQP 消息。| | | |
|
taskExecutor
(任务执行器)| 对 Spring TaskExecutor（或标准的 JDK 1.5+ Executor）的引用，用于执行监听器调用器。默认是 SimpleAsyncTaskExecutor，使用内部管理的线程。| | | |
|
taskScheduler
(任务调度器)| 使用 DMLC 时，调度器会在 monitorInterval 时间间隔运行监控任务。| | | |
|
transactionManager
(transaction-manager)| 用于监听器操作的外部事务管理器。同时也是对 channelTransacted 的补充——如果 Channel 是事务性的，则其事务将与外部事务同步。| | | |