4. 消息契约的组成要素：消息Key、消息Value、Header、Schema、序列化方式

消息契约是Kafka集成验证的核心，它定义了生产者和消费者之间必须遵守的数据格式与语义约定。一个完整的Kafka消息契约由五个核心要素构成：消息Key、消息Value、Header、Schema和序列化方式。在复测场景中，任何要素的偏差都可能导致消费端解析失败或数据一致性受损。

4.1 消息Key与消息Value

消息Key和Value是Kafka消息的主体载荷。Key用于分区路由和日志压缩，Value承载业务数据。在契约验证中，两者的数据类型、长度约束和空值策略都需要明确约定。

4.2 Header：消息的元数据扩展

Kafka Header是0.11版本引入的键值对结构，用于携带消息的元数据信息，如追踪ID、版本号、路由标签等。Header不参与分区路由，但可以被消费者和中间件用于过滤、追踪和路由决策。

• Header结构： 每个Header由Key（String）和Value（byte[]）组成，一个消息可包含多个Header。
• 常见用途： 消息来源标识、事件类型标记、链路追踪TraceId、Schema版本号。
• 复测要点： Header的编码一致性（UTF-8 vs 二进制）、Header数量上限（默认无限制，但过多影响性能）、Header值长度限制。

// 生产者设置Header示例
ProducerRecord<String, Order> record = new ProducerRecord<>("order-topic", orderId, order);
record.headers().add("traceId", "abc-123".getBytes(StandardCharsets.UTF_8));
record.headers().add("schemaVersion", "2".getBytes(StandardCharsets.UTF_8));
producer.send(record);

4.3 Schema：数据结构的契约定义

Schema是消息契约中最关键的要素，它定义了消息Value（和Key）的数据结构、字段类型、默认值和兼容性规则。在Kafka生态中，Schema Registry是管理Schema的事实标准。

4.4 序列化方式：从对象到字节流的桥梁

序列化方式决定了消息Key和Value在网络上传输和磁盘存储的字节表示。Kafka允许为Key和Value分别指定不同的序列化器。序列化方式必须与Schema配合使用，否则无法正确解析数据。

• 内置序列化器： StringSerializer、ByteArraySerializer、LongSerializer、IntegerSerializer。
• Schema感知序列化器： KafkaAvroSerializer、KafkaProtobufSerializer、KafkaJsonSchemaSerializer。
• 自定义序列化器： 实现Serializer接口，需注意线程安全和版本兼容。

// 生产者配置：Key使用String序列化，Value使用Avro序列化
props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, 
          "org.apache.kafka.common.serialization.StringSerializer");
props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, 
          "io.confluent.kafka.serializers.KafkaAvroSerializer");
props.put("schema.registry.url", "http://schema-registry:8081");

4.5 五要素的集成关系

消息契约的五个要素不是孤立的，它们在生产-消费链路中形成完整的契约链。下图展示了消息从生产者到消费者的完整序列化与反序列化流程，以及各要素的交互关系。

4.6 复测场景中的契约验证清单

在集成验证阶段，复测脚本需要针对每个要素设计独立的测试用例，并验证要素之间的组合场景。以下清单可作为测试用例设计的参考基线：

1. Key验证： Key为null、空字符串、超长字符串（超过默认max.message.bytes）；Key类型与分区器是否匹配。
2. Value验证： Value为null、空对象、字段缺失、字段类型错误；Value大小超过Broker限制。
3. Header验证： Header Key重复、Header Value为null、Header数量超过100个；Header编码与消费者预期不一致。
4. Schema验证： Schema注册失败、Schema版本不兼容、Schema字段顺序变化、Schema删除字段后旧消费者行为。
5. 序列化方式验证： 生产者和消费者序列化器不匹配、序列化器配置缺失、自定义序列化器抛出异常。