一文带你理解Kafka的Header

Kafka Header 是消息中的元数据区域，可以在不改变消息 value 的情况下携带附加信息。它适合存放追踪标识、消息类型、版本号、来源系统、租户标识等与消息处理有关但不属于业务主体的数据。

Header 解决什么问题

在没有 Header 时，很多团队会把元数据塞进消息体中，例如在 JSON 里增加 traceId、eventType、schemaVersion。这样虽然可行，但会让业务数据和控制信息混在一起，也会增加不同消费者解析消息体的耦合。

Header 提供了更轻量的方式。生产者发送消息时可以附加多个键值对，消费者在处理消息前读取 Header，根据元数据决定路由、反序列化、日志追踪或兼容处理。

常见使用场景

第一是链路追踪。生产者把 traceId 或 requestId 写入 Header，下游消费者记录日志时继续传递，便于排查跨系统问题。第二是消息版本控制。不同版本的消息体可能字段不同，消费者可以根据 Header 中的版本选择解析逻辑。

第三是类型标识。一个 topic 中如果承载多个事件类型，可以通过 Header 标明事件名称，但是否混用 topic 仍要结合治理规则判断。第四是安全与租户信息，例如标记数据来源或租户，但敏感信息不应直接以明文写入 Header。

Java 客户端示例

生产者可以在 ProducerRecord 中添加 Header：

ProducerRecord<String, String> record =
    new ProducerRecord<>("demo-topic", "key", "value");
record.headers().add("traceId", "abc-123".getBytes(StandardCharsets.UTF_8));
producer.send(record);

消费者读取 Header 时，需要处理字节数组和可能不存在的情况：

Header header = consumerRecord.headers().lastHeader("traceId");
if (header != null) {
    String traceId = new String(header.value(), StandardCharsets.UTF_8);
}

使用注意事项

Header 不适合存放大体积数据，也不应替代消息体。它更像消息的“标签”和“控制信息”。如果元数据直接影响业务事实，仍应放入消息体并纳入 Schema 管理。

另外，不同客户端、连接器和中间处理组件对 Header 的支持程度可能不同。设计消息链路时，要确认生产、消费、同步、转换和落库环节是否会保留 Header，避免元数据在中途丢失。