消息格式

这一课你将能做到

1. 用 JSON 定义 OrderCreated 事件信封，经 KafkaTemplate 发送并用 ObjectMapper 反序列化消费
2. 对照表格说清「新增可选字段 / 删字段 / 改类型 / 改字段名」对兼容性的影响，并给出安全的演进顺序
3. 说清实验阶段为何优先 JSON，以及 Avro + Schema Registry 解决什么问题（概念级）

为什么要学

Kafka Broker 只存字节：不帮你校验字段、不帮你做版本迁移。团队如果各写各的 JSON，消费方迟早翻车在「缺字段 / 类型变了 / 同名异义」上——这类事故在日志里只是一行 JsonProcessingException，排查半天才发现是上游偷偷改了字段类型。

消息格式就是 Topic 的公共 API：生产者与消费者的契约。本站 REST 用 Jackson + JSON，事件流先沿用同一套最顺手；等跨语言、多团队共享 Topic、需要自动兼容检查时，再上 Avro + Schema Registry。

人话：Topic 是管道，契约在消息格式。管道不会替你检查内容，契约坏了下游全坏。

先建立图像

Producer                         Broker                      Consumer
  POJO/Map ──序列化──► bytes ──► 分区日志 ──► bytes ──反序列化──► POJO
                │                                      │
                └── 契约：字段名、类型、兼容规则 ──────┘

Avro + Registry（概念图）：
  Producer 注册 schema → 消息头带 schema id → [magic][id][avro bytes]
  Consumer 按 id 向 Registry 取 schema → 反序列化
  → 兼容性在注册时强制检查

方案	优点	代价	何时用
JSON 字符串	可读、易调试、与 REST 同栈	无强 schema、体积大	实验 / 小团队
JSON Schema	可校验	治理靠自觉	中等规模
Avro + Registry	紧凑、多语言、强制兼容检查	要运维 Registry	多团队事件总线

跟着做

步骤 1：定一条事件契约（纸上）

写下最小字段，规则：event（类型）+ eventId（幂等键）+ 业务主键 + 发生时间：

{
  "event": "OrderCreated",
  "eventId": "01JBEXAMPLEUUID",
  "orderId": "1001",
  "userId": "u42",
  "amount": 9900,
  "occurredAt": "2026-10-06T00:00:00Z"
}

约定写进笔记：payload 带够用的只读快照（金额、用户），避免消费方事事回查生产方数据库；写路径冲突仍以 MySQL 事务为准。

步骤 2：Java record + 发送

public record OrderCreatedEvent(
        String event,
        String eventId,
        String orderId,
        String userId,
        long amount,
        Instant occurredAt
) {}

// 发送侧：对象 → JSON 字符串（实验序列化策略）
OrderCreatedEvent evt = new OrderCreatedEvent(
        "OrderCreated",
        UUID.randomUUID().toString(),
        "1001", "u42", 9900L, Instant.now());
String json = objectMapper.writeValueAsString(evt);
// key=orderId → 同订单分区内有序（生产者课的纪律）
kafkaTemplate.send("coderoadmap.order-events", evt.orderId(), json);