跳到主要内容
版本：5.0.1

记录序列化与反序列化

DeepSeek V3 中英对照 Record serialization and deserialization

Kafka Streams binder 允许您以两种方式序列化和反序列化记录。一种是 Kafka 提供的原生序列化和反序列化功能，另一种是 Spring Cloud Stream 框架的消息转换能力。让我们来看一些细节。

入站反序列化​

键始终使用原生序列化/反序列化器进行反序列化。

对于值（values），默认情况下，入站（inbound）的反序列化由 Kafka 原生执行。请注意，这是 Kafka Streams binder 默认行为的一个重大变化，在之前的版本中，反序列化是由框架完成的。

Kafka Streams binder 会尝试通过查看 java.util.function.Function|Consumer 的类型签名来推断匹配的 Serde 类型。以下是它匹配 Serdes 的顺序。

  • 如果应用程序提供了一个类型为 Serde 的 bean，并且返回类型使用了传入键或值类型的实际类型进行参数化，那么它将使用该 Serde 进行入站反序列化。例如，如果应用程序中存在以下内容，绑定器会检测到 KStream 的传入值类型与一个在 Serde bean 上参数化的类型匹配。它将使用该 bean 进行入站反序列化。
@Bean
public Serde<Foo> customSerde() {
 ...
}

@Bean
public Function<KStream<String, Foo>, KStream<String, Foo>> process() {
}

  • 接下来，它会检查类型，看它们是否是 Kafka Streams 公开的类型之一。如果是，就使用它们。以下是绑定器将尝试从 Kafka Streams 匹配的 Serde 类型。

    Integer, Long, Short, Double, Float, byte[], UUID and String.

  • 如果 Kafka Streams 提供的 Serdes 都不匹配类型，那么它将使用 Spring Kafka 提供的 JsonSerde。在这种情况下，绑定器假设这些类型是 JSON 友好的。如果你有多个值对象作为输入，这将非常有用，因为绑定器会在内部将它们推断为正确的 Java 类型。不过，在回退到 JacksonJsonSerde 之前，绑定器会检查 Kafka Streams 配置中设置的默认 Serde，以查看它是否是与传入 KStream 类型匹配的 Serde。

如果以上策略均未生效，则应用程序必须通过配置提供 Serde。这可以通过两种方式进行配置——绑定或默认。

首先，绑定器会检查在绑定级别是否提供了 Serde。例如，如果你有以下处理器，

@Bean
public BiFunction<KStream<CustomKey, AvroIn1>, KTable<CustomKey, AvroIn2>, KStream<CustomKey, AvroOutput>> process() {...}

那么，你可以使用以下方式提供一个绑定级别的 Serde：

spring.cloud.stream.kafka.streams.bindings.process-in-0.consumer.keySerde=CustomKeySerde
spring.cloud.stream.kafka.streams.bindings.process-in-0.consumer.valueSerde=io.confluent.kafka.streams.serdes.avro.SpecificAvroSerde

spring.cloud.stream.kafka.streams.bindings.process-in-1.consumer.keySerde=CustomKeySerde
spring.cloud.stream.kafka.streams.bindings.process-in-1.consumer.valueSerde=io.confluent.kafka.streams.serdes.avro.SpecificAvroSerde
备注

如果你像上面那样为每个输入绑定提供 Serde，那么这将具有更高的优先级，绑定器将不会进行任何 Serde 推断。

如果您希望使用默认的键/值序列化/反序列化器进行入站反序列化，可以在绑定器级别进行配置。

spring.cloud.stream.kafka.streams.binder.configuration.default.key.serde
spring.cloud.stream.kafka.streams.binder.configuration.default.value.serde

如果你不希望使用 Kafka 提供的原生解码功能，可以依赖 Spring Cloud Stream 提供的消息转换特性。由于原生解码是默认启用的，为了让 Spring Cloud Stream 反序列化入站的值对象，你需要显式地禁用原生解码。

例如，如果你有与上述相同的 BiFunction 处理器，那么 spring.cloud.stream.bindings.process-in-0.consumer.nativeDecoding: false 你需要为所有输入单独禁用原生解码。否则，对于那些你没有禁用的输入，仍然会应用原生解码。

默认情况下，Spring Cloud Stream 将使用 application/json 作为内容类型，并使用相应的 JSON 消息转换器。您可以通过以下属性和适当的 MessageConverter bean 来使用自定义消息转换器。

spring.cloud.stream.bindings.process-in-0.contentType

出站序列化​

出站序列化基本遵循与入站反序列化相同的规则。与入站反序列化一样，相较于先前版本的 Spring Cloud Stream，一个主要变化是出站序列化由 Kafka 原生处理。在绑定器 3.0 版本之前，这是由框架本身完成的。

出站消息的键始终由 Kafka 使用匹配的 Serde 进行序列化，该 Serde 由绑定器推断得出。如果无法推断键的类型，则需要通过配置进行指定。

值序列化/反序列化器（serdes）的推断遵循与入站反序列化相同的规则。首先，它会检查出站类型是否来自应用程序中提供的Bean。如果不是，则检查是否与Kafka暴露的Serde匹配，例如 - Integer、Long、Short、Double、Float、byte[]、UUID 和 String。如果这也不匹配，则会回退到Spring Kafka项目提供的JacksonJsonSerde，但在此之前会先查看默认的Serde配置以寻找匹配项。请注意，所有这些过程对应用程序都是透明的。如果以上方法均不适用，则用户必须通过配置提供要使用的Serde。

假设你正在使用与上述相同的 BiFunction 处理器。那么你可以按如下方式配置出站键/值序列化/反序列化器。

spring.cloud.stream.kafka.streams.bindings.process-out-0.producer.keySerde=CustomKeySerde
spring.cloud.stream.kafka.streams.bindings.process-out-0.producer.valueSerde=io.confluent.kafka.streams.serdes.avro.SpecificAvroSerde

如果 Serde 推断失败，且未提供绑定级别的 Serde，那么绑定器将回退到 JacksonJsonSerde，但会查找默认的 Serde 以寻找匹配项。

默认的序列化/反序列化器（serdes）的配置方式与上述反序列化部分所述相同。

spring.cloud.stream.kafka.streams.binder.configuration.default.key.serde spring.cloud.stream.kafka.streams.binder.configuration.default.value.serde

如果你的应用程序使用了分支功能并具有多个输出绑定，那么这些绑定必须按绑定进行配置。再次强调，如果绑定器能够推断出 Serde 类型，你就不需要进行此配置。

如果您不希望使用 Kafka 提供的原生编码，而是希望使用框架提供的消息转换，那么您需要显式禁用原生编码，因为原生编码是默认设置。例如，如果您有与上述相同的 BiFunction 处理器，那么 spring.cloud.stream.bindings.process-out-0.producer.useNativeEncoding: false 您需要在分支的情况下为所有输出单独禁用原生编码。否则，对于那些您未禁用的输出，仍将应用原生编码。

当 Spring Cloud Stream 进行转换时，默认情况下，它将使用 application/json 作为内容类型，并使用适当的 JSON 消息转换器。您可以通过以下属性和相应的 MessageConverter bean 来使用自定义消息转换器。

spring.cloud.stream.bindings.process-out-0.contentType

当禁用原生编码/解码时，binder 不会像原生 Serdes 那样进行任何推断。应用程序需要显式提供所有配置选项。因此，通常建议在编写 Spring Cloud Stream Kafka Streams 应用程序时，保持默认的序列化/反序列化选项，并坚持使用 Kafka Streams 提供的原生序列化/反序列化。唯一必须使用框架提供的消息转换能力的情况是，当你的上游生产者使用了特定的序列化策略时。在这种情况下，你需要使用匹配的反序列化策略，因为原生机制可能会失败。当依赖默认的 Serde 机制时，应用程序必须确保 binder 能够通过正确的 Serde 正确映射入站和出站，否则可能会导致失败。

值得一提的是，上述数据序列化/反序列化方法仅适用于处理器的边缘，即入站和出站。您的业务逻辑可能仍需要调用明确需要 Serde 对象的 Kafka Streams API。这些仍由应用程序负责，必须由开发者相应处理。