监听容器属性

Doubao 中英对照 Listener Container Properties

表 1. ContainerProperties 属性

属性	默认值	描述
ackCount	1	当 ackMode 为 COUNT 或 COUNT_TIME 时，提交待处理偏移量之前的记录数。
adviceChain	null	包裹消息监听器的 Advice 对象链（例如 MethodInterceptor 环绕通知），按顺序调用。
ackMode	BATCH	控制提交偏移量的频率——参见 提交偏移量。
ackTime	5000	当 ackMode 为 TIME 或 COUNT_TIME 时，提交待处理偏移量所经过的时间（毫秒）。
assignmentCommitOption	LATEST_ONLY _NO_TX	是否在分配时提交初始位置；默认情况下，仅当 ConsumerConfig.AUTO_OFFSET_RESET_CONFIG 为 latest 时才会提交初始偏移量，并且即使存在事务管理器也不会在事务中运行。有关可用选项的更多信息，请参阅 ContainerProperties.AssignmentCommitOption 的 JavaDocs。
asyncAcks	false	启用乱序提交（参见 手动提交偏移量）；消费者被暂停，提交被推迟直到空缺被填补。
authExceptionRetryInterval	null	非 null 时，当 Kafka 客户端抛出 AuthenticationException 或 AuthorizationException 时，轮询之间休眠的 Duration。为 null 时，此类异常被视为致命，容器将停止。
batchRecoverAfterRollback	false	设置为 true 以启用批量恢复，参见 回滚后处理器。
clientId	（空字符串）	client.id 消费者属性的前缀。覆盖消费者工厂的 client.id 属性；在并发容器中，为每个消费者实例添加 -n 后缀。
checkDeserExWhenKeyNull	false	设置为 true，以便在收到 null key 时始终检查 DeserializationException 头。当消费者代码无法确定是否配置了 ErrorHandlingDeserializer 时（例如使用委托反序列化器时）很有用。
checkDeserExWhenValueNull	false	设置为 true，以便在收到 null value 时始终检查 DeserializationException 头。当消费者代码无法确定是否配置了 ErrorHandlingDeserializer 时（例如使用委托反序列化器时）很有用。
commitCallback	null	当存在且 syncCommits 为 false 时，提交完成后调用的回调。
commitLogLevel	DEBUG	与提交偏移量相关日志的日志级别。
consumerRebalanceListener	null	一个再均衡监听器；参见 再均衡监听器。
commitRetries	3	当使用 syncCommits 设为 true 时，设置 RetriableCommitFailedException 的重试次数。默认 3（共 4 次尝试）。
consumerStartTimeout	30s	在记录错误之前等待消费者启动的时间；例如当你使用线程不足的任务执行器时可能发生。
deliveryAttemptHeader	false	参见 投递尝试头。
eosMode	V2	恰好一次语义模式；参见 恰好一次语义。
fixTxOffsets	false	当消费由事务性生产者产生的记录，且消费者位于分区末尾时，由于用于指示事务提交/回滚的伪记录以及可能存在的被回滚记录，滞后（lag）可能被错误地报告为大于零。这在功能上不影响消费者，但一些用户对 "lag" 非零表示担忧。将此属性设为 true，容器将纠正此类误报的偏移量。该检查在下一次 poll 之前执行，以避免给提交处理增加显著复杂度。在撰写本文时，仅当消费者配置为 isolation.level=read_committed 且 max.poll.records 大于 1 时才会纠正 lag。更多信息请参阅 KAFKA-10683。
groupId	null	覆盖消费者的 group.id 属性；由 @KafkaListener 的 id 或 groupId 属性自动设置。
idleBeforeDataMultiplier	5.0	在收到任何记录之前应用于 idleEventInterval 的乘数。收到一条记录后，该乘数不再应用。自 2.8 版本起可用。
idleBetweenPolls	0	通过在线程轮询之间休眠来减缓投递。处理一批记录的时间加上此值必须小于 max.poll.interval.ms 消费者属性。
idleEventInterval	null	设置后，启用 ListenerContainerIdleEvent 的发布，参见 应用程序事件 和 检测空闲和无响应的消费者。另见 idleBeforeDataMultiplier。
idlePartitionEventInterval	null	设置后，启用 ListenerContainerIdlePartitionEvent 的发布，参见 应用程序事件 和 检测空闲和无响应的消费者。
kafkaConsumerProperties	无	用于覆盖在消费者工厂上配置的任意消费者属性。
kafkaAwareTransactionManager	null	参见 事务。
listenerTaskExecutor	SimpleAsyncTaskExecutor	用于运行消费者线程的任务执行器。默认执行器创建名为 <name>-C-n 的线程；对于 KafkaMessageListenerContainer，名称为 bean 名称；对于 ConcurrentMessageListenerContainer，名称为 bean 名称加 -m 后缀，其中 m 为每个子容器递增。参见 容器线程命名。
logContainerConfig	false	设置为 true，以 INFO 级别记录所有容器属性。
messageListener	null	处理从 Kafka 主题消费的记录的消息监听器。
micrometerEnabled	true	是否为消费者线程维护 Micrometer 计时器。
micrometerTags	空	要添加到 micrometer 指标的静态标签映射。
micrometerTagsProvider	null	基于消费者记录提供动态标签的函数。
missingTopicsFatal	false	为 true 时，如果配置的主题在代理上不存在，则阻止容器启动。
monitorInterval	30s	检查消费者线程状态以发现 NonResponsiveConsumerEvent 的频率。参见 noPollThreshold 和 pollTimeout。
noPollThreshold	3.0	乘以 pollTimeOut 以确定是否发布 NonResponsiveConsumerEvent。参见 monitorInterval。
observationConvention	null	设置后，基于消费者记录中的信息向计时器和追踪添加动态标签。
observationEnabled	false	设置为 true 以通过 Micrometer 启用观测。
offsetAndMetadataProvider	null	用于 OffsetAndMetadata 的提供者；默认情况下，该提供者创建一个元数据为空的偏移量和元数据。该提供者提供了一种自定义元数据的方式。
onlyLogRecordMetadata	false	设置为 false 以记录完整的消费者记录（在错误、调试日志等中），而不仅仅是 topic-partition@offset。
pauseImmediate	false	容器暂停时，在当前记录之后停止处理，而不是在处理完上一次 poll 的所有记录之后；剩余记录保留在内存中，并在容器恢复时传递给监听器。
pollTimeout	5000	传入 Consumer.poll() 的超时时间（毫秒）。
pollTimeoutWhilePaused	100	容器处于暂停状态时传入 Consumer.poll() 的超时时间（毫秒）。
restartAfterAuthExceptions	false	为 true 时，如果容器因授权/认证异常而停止，则重启容器。
scheduler	ThreadPoolTaskScheduler	用于运行消费者监控任务的调度器。
shutdownTimeout	10000	阻塞 stop() 方法的最长时间（ms），直到所有消费者停止，并在发布容器停止事件之前。
stopContainerWhenFenced	false	如果抛出 ProducerFencedException，停止监听容器。更多信息请参阅 回滚后处理器。
stopImmediate	false	容器停止时，在当前记录之后停止处理，而不是在处理完上一次 poll 的所有记录之后。
subBatchPerPartition	见描述	使用批量监听器时，如果为 true，则将 poll 结果拆分为子批次后调用监听器，每个分区一个。默认 false。
syncCommitTimeout	null	当 syncCommits 为 true 时使用的超时时间。未设置时，容器将尝试确定 default.api.timeout.ms 消费者属性并使用它；否则使用 60 秒。
syncCommits	true	对偏移量使用同步还是异步提交；参见 commitCallback。
topics topicPattern topicPartitions	n/a	配置的主题、主题模式或显式分配的主题/分区。互斥；必须至少提供一个；由 ContainerProperties 构造函数强制实施。
transactionManager	null	自 3.2 起弃用，参见 [kafkaAwareTransactionManager]、其他事务管理器。

表 2. AbstractMessageListenerContainer 属性

属性	默认值	描述
afterRollbackProcessor	DefaultAfterRollbackProcessor	在事务回滚后调用的 AfterRollbackProcessor。
applicationEventPublisher	应用程序上下文	事件发布者。
batchErrorHandler	见描述	已弃用——参见 commonErrorHandler。
batchInterceptor	null	设置一个 BatchInterceptor，在调用批量监听器之前调用；不适用于记录监听器。另见 interceptBeforeTx。
beanName	bean 名称	容器的 bean 名称；子容器加 -n 后缀。
commonErrorHandler	见描述	当使用 DefaultAfterRollbackProcessor 时提供了 transactionManager，则为 DefaultErrorHandler 或 null。参见 容器错误处理器。
containerProperties	ContainerProperties	容器属性实例。
groupId	见描述	containerProperties.groupId（如果存在），否则来自消费者工厂的 group.id 属性。
interceptBeforeTx	true	决定 recordInterceptor 在事务开始之前还是之后调用。
listenerId	见描述	用户配置容器的 bean 名称，或 @KafkaListener 的 id 属性。
listenerInfo	null	要填充到 KafkaHeaders.LISTENER_INFO 头中的值。使用 @KafkaListener 时，该值从 info 属性获取。此头可用于各处，例如 RecordInterceptor、RecordFilterStrategy 以及监听器代码本身。
pauseRequested	（只读）	如果已请求消费者暂停，则为 True。
recordInterceptor	null	设置一个 RecordInterceptor，在调用记录监听器之前调用；不适用于批量监听器。另见 interceptBeforeTx。
topicCheckTimeout	30s	当 missingTopicsFatal 容器属性为 true 时，等待 describeTopics 操作完成的时间（秒）。

表 3. KafkaMessageListenerContainer 属性

属性	默认值	描述
assignedPartitions	（只读）	当前分配给此容器的分区（显式或非显式）。
clientIdSuffix	null	由并发容器使用，为每个子容器的消费者提供唯一的 client.id。
containerPaused	n/a	如果已请求暂停且消费者已实际暂停，则为 True。

表 4. ConcurrentMessageListenerContainer 属性

属性	默认值	描述
alwaysClientIdSuffix	true	当 concurrency 仅为 1 时，设置为 false 以抑制为 client.id 消费者属性添加后缀。
assignedPartitions	（只读）	当前分配给此容器子 KafkaMessageListenerContainer 的分区总和（显式或非显式）。
concurrency	1	要管理的子 KafkaMessageListenerContainer 数量。
containerPaused	n/a	如果已请求暂停且所有子容器的消费者已实际暂停，则为 True。
containers	n/a	对所有子 KafkaMessageListenerContainer 的引用。