这个版本仍在开发中，目前尚未被认为是稳定的。要使用最新稳定版本，请使用 Spring for Apache Kafka 4.0.4！spring-doc.cadn.net.cn

什么是新内容？

4.0 有哪些新内容（自 3.3 起）

这一部分涵盖了从版本3.3到版本4.0所做的更改。对于早期版本的变更历史，请参阅变更历史。spring-doc.cadn.net.cn

Apache Kafka 4.0 客户端升级

Spring for Apache Kafka 已升级以使用 Apache Kafka 客户端版本 4.0.0。此次升级带来了几个重要的更改：spring-doc.cadn.net.cn

所有基于ZooKeeper的功能已在Kafka 4.0完全过渡到KRaft模式时被移除spring-doc.cadn.net.cn
移除了ZooKeeper依赖项spring-doc.cadn.net.cn
嵌入式Kafka测试框架现在仅使用KRaft模式spring-doc.cadn.net.cn
The EmbeddedKafkaZKBroker 类已移除，所有功能现在都由 EmbeddedKafkaKraftBroker 处理spring-doc.cadn.net.cn

嵌入式Kafka测试框架更改

测试基础设施已得到显著更新：spring-doc.cadn.net.cn

The EmbeddedKafkaRule JUnit 4 rule has been removedspring-doc.cadn.net.cn
The @EmbeddedKafka 注解已简化，移除了与 ZooKeeper 相关的属性:spring-doc.cadn.net.cn
The kraft 属性已移除，因为 KRaft 模式现在是唯一选项spring-doc.cadn.net.cn
ZooKeeper-specific properties 例如 zookeeperPort、zkConnectionTimeout 和 zkSessionTimeout 已经被移除spring-doc.cadn.net.cn
KafkaClusterTestKit 现在导入用于 KRaft 模式的新的包spring-doc.cadn.net.cn
一些测试已更新以解决KRaft模式中静态端口分配的限制spring-doc.cadn.net.cn
针对测试中的复制因子进行了调整，以适应KRaft要求spring-doc.cadn.net.cn

消费者记录构建器更改

The ConsumerRecords 构造函数现在需要一个额外的 Map 参数，这一变更已在整个框架中得到处理。直接使用此构造函数的应用程序将需要更新其代码。spring-doc.cadn.net.cn

生产者接口更新

新的 Kafka 生产者接口方法已实现:spring-doc.cadn.net.cn

registerMetricForSubscriptionspring-doc.cadn.net.cn
unregisterMetricFromSubscriptionspring-doc.cadn.net.cn

移除已弃用功能

已移除几个已弃用的项目:spring-doc.cadn.net.cn

已弃用的 partitioner 类已从运行时提示中移除spring-doc.cadn.net.cn
已弃用的 sendOffsetsToTransaction 方法，该方法使用 String consumerGroupId 已被移除spring-doc.cadn.net.cn

Kafka Streams API 变更

KafkaStreamBrancher 已更新以使用新的 split() 和 branch() 方法，而不是已弃用的 branch() 方法spring-doc.cadn.net.cn
The DeserializationExceptionHandler has been updated to use the new ErrorHandlerContextspring-doc.cadn.net.cn

内部 API 更新，与 Apache Kafka 4.0.0 相关

The BrokerAddress 类现在使用 org.apache.kafka.server.network.BrokerEndPoint 代替已弃用的 kafka.cluster.BrokerEndPointspring-doc.cadn.net.cn
The GlobalEmbeddedKafkaTestExecutionListener has been updated to work solely with KRaft modespring-doc.cadn.net.cn

新消费者重平衡协议

Spring for Apache Kafka 4.0 支持 Kafka 4.0 的新消费者重新平衡协议 - KIP-848。对于详情，请参见新消费者重新平衡协议文档。spring-doc.cadn.net.cn

支持多值头

The JsonKafkaHeaderMapper and SimpleKafkaHeaderMapper 支持为 Kafka 记录的多值头映射。更多详情请参阅支持多值头映射。spring-doc.cadn.net.cn

配置额外的`RecordInterceptor`

监听器容器现在支持通过 getRecordInterceptor() 进行拦截器自定义。详见消息监听器容器部分的说明。spring-doc.cadn.net.cn

每条记录的批处理监听器观察

现在可以为使用批处理监听器时的每条记录获取观察值。请参阅批处理监听器的可观测性以获取更多信息。spring-doc.cadn.net.cn

Kafka 队列（共享消费者）支持

Spring for Apache Kafka 现在通过 share consumers 提供 Kafka Queues 的早期访问支持，这些 share consumers 是 Apache Kafka 4.0.0 的一部分，实现了 KIP-932。这使得多个消费者可以同时从相同的分区消费，相比传统的 consumer groups 提供了更好的负载分布。见 Kafka Queues (Share Consumer) 了解更多信息。spring-doc.cadn.net.cn

Jackson 3 支持

Spring for Apache Kafka 现在提供了对 Jackson 3 的全面支持，同时保留对 Jackson 2 的支持。当可用时，Jackson 3 会自动检测并优先使用，提供增强的性能和现代的 JSON 处理能力。spring-doc.cadn.net.cn

所有 Jackson 2 类现在都有与之对应的 Jackson 3 类，命名一致且类型安全性得到提升：spring-doc.cadn.net.cn

JsonKafkaHeaderMapper 替换 DefaultKafkaHeaderMapperspring-doc.cadn.net.cn
JacksonJsonSerializer/Deserializer 替换 JsonSerializer/Deserializerspring-doc.cadn.net.cn
JacksonJsonSerde 替换 JsonSerdespring-doc.cadn.net.cn
JacksonJsonMessageConverter 家族替换 JsonMessageConverter 家族spring-doc.cadn.net.cn
JacksonProjectingMessageConverter 替换 ProjectingMessageConverterspring-doc.cadn.net.cn
DefaultJacksonJavaTypeMapper 替换 DefaultJackson2JavaTypeMapperspring-doc.cadn.net.cn

新的 Jackson 3 类使用 JsonMapper 代替泛型 ObjectMapper 以增强类型安全性，并利用了 Jackson 3 改进的模块系统和性能优化。spring-doc.cadn.net.cn

迁移路径: 现有应用程序在添加 Jackson 3 到类路径且更新类引用以使用新的 Jackson 3 等价项后将继续正常工作。要迁移到 Jackson 3，只需将 Jackson 3 添加到您的类路径并更新类引用以使用新的 Jackson 3 等价项。当两种版本同时存在时，框架会自动检测并优先选择 Jackson 3。spring-doc.cadn.net.cn

向后兼容性: 所有 Jackson 2 类都已弃用但仍然完全功能正常。它们将在未来的一个重大版本中移除。spring-doc.cadn.net.cn

见序列化、反序列化和消息转换中的配置示例。spring-doc.cadn.net.cn

Spring 重试依赖移除

Spring for Apache Kafka 已移除对其上 Spring Retry 的依赖，转而使用在 Spring Framework 7 中引入的核心重试支持。这是一个影响整个框架重试配置和 API 的重大变更。spring-doc.cadn.net.cn

BackOffValuesGenerator 会在启动时预先生成所需的BackOff值，现在可以直接与 Spring Framework 的BackOff接口配合，而不再使用BackOffPolicy。这些值由监听器基础设施进行管理，Spring Retry 也不再参与。spring-doc.cadn.net.cn

从配置的角度来看，Spring Kafka 严重依赖于 Spring Retry 的 @Backoff 注解。由于 Spring 框架中没有等效的注解，该注解已移动到 Spring Kafka 作为 @BackOff，并带有以下改进：spring-doc.cadn.net.cn

统一命名：使用 @BackOff 代替 @Backoff 以保持一致性spring-doc.cadn.net.cn
表达式评估：所有字符串属性都支持SpEL表达式和属性占位符spring-doc.cadn.net.cn
Duration format support: String attributes accept java.util.Duration formats (e.g., "2s", "500ms")spring-doc.cadn.net.cn
增强文档：带有更清晰解释的改进型Javadocspring-doc.cadn.net.cn

迁移示例:spring-doc.cadn.net.cn

// Before
@RetryableTopic(backoff = @Backoff(delay = 2000, maxDelay = 10000, multiplier = 2))

// After
@RetryableTopic(backOff = @BackOff(delay = 2000, maxDelay = 10000, multiplier = 2))

// With new duration format support
@RetryableTopic(backOff = @BackOff(delayString = "2s", maxDelayString = "10s", multiplier = 2))

// With property placeholders
@RetryableTopic(backOff = @BackOff(delayString = "${retry.delay}", multiplierString = "${retry.multiplier}"))

RetryingDeserializer 不再提供 RecoveryCallback，而是提供一个以 RetryException 为输入的等效功能。此内容包含抛出的异常以及重试尝试的次数：spring-doc.cadn.net.cn

// Before
retryingDeserializer.setRecoveryCallback(context -> {
    return fallbackValue;
});

// After
retryingDeserializer.setRecoveryCallback(retryException -> {
    return fallbackValue;
});

使用 BinaryExceptionClassifier 已被新引入的 ExceptionMatcher 取代，后者提供了一个更精致的 API。spring-doc.cadn.net.cn

额外的更改包括：spring-doc.cadn.net.cn

DestinationTopicPropertiesFactory 使用 ExceptionMatcher 代替 BinaryExceptionClassifierspring-doc.cadn.net.cn
The uniformRandomBackoff 方法在 RetryTopicConfigurationBuilder 中已弃用，推荐使用 jitter 支持spring-doc.cadn.net.cn
错误处理实用工具已更新以与新的异常匹配系统配合使用spring-doc.cadn.net.cn
Kafka Streams retry templates now use Spring Framework’s retry supportspring-doc.cadn.net.cn

应用程序必须更新其配置以使用新的 Spring Framework 重试 API，但重试行为和功能保持不变。spring-doc.cadn.net.cn