5.4 Schema：结构化消息的质检标签

5.4 Schema：结构化消息的质检标签

本节摘要：裸消息是字节，业务要的是对象。Schema 让主题带上类型声明：生产者不能发不符合结构的消息，消费者收到的直接是带字段的对象；更重要的是兼容性策略能在"改字段毁下游"的事故发生前拦下它。本节用订单事件的演进史演示声明、序列化与兼容拦截的完整闭环。

给货物贴上质检标签

没有 Schema 的主题像没有报关单的集装箱：里面装什么全凭自觉，生产者改了字段格式，下游解析崩了才知道。Pulsar 的 Schema 机制给主题立了契约——主题一旦声明 Schema，服务端会在写入时校验载荷结构，并在读取时直接反序列化成对象交给消费者。一份契约管住两端，错误在入口就被拒绝，而不是在下游的异常日志里被发现。

对业务的真实价值在演进时刻：订单事件要加"优惠金额"字段了，老消费者会不会崩？契约机制用兼容性策略回答：命名空间或主题上声明"向后兼容"（新 Schema 能读旧数据）或"完全兼容"（新旧互读）等策略，不满足策略的新 Schema 直接注册失败——上游想改字段，集群先替下游把关。

一、声明与收发：JSON Schema 的完整闭环

从零跑通一遍。生产者侧声明 Schema 并发送结构化订单事件：

public class OrderEvent {
    private String orderId;
    private long amount;
    private String status;
    // 省略 getter 与 setter：Schema 库按字段生成结构描述
}

Producer<OrderEvent> producer = client.newProducer(Schema.JSON(OrderEvent.class))
        .topic("persistent://trade-order/transaction/order-events")
        .create();   // 首次创建：Schema 随生产者注册到主题

OrderEvent evt = new OrderEvent();
evt.setOrderId("order-1024");
evt.setAmount(19900);
evt.setStatus("CREATED");
MessageId id = producer.newMessage().key(evt.getOrderId()).value(evt).send();
System.out.println("结构化消息已入仓: " + id);
​

消费者侧用同样的 Schema 声明，取到的直接是对象：

Consumer<OrderEvent> consumer = client.newConsumer(Schema.JSON(OrderEvent.class))
        .topic("persistent://trade-order/transaction/order-events")
        .subscriptionName("stock-deduct")
        .subscriptionType(SubscriptionType.Key_Shared)
        .subscribe();

OrderEvent evt = consumer.receive().getValue();   // 已是对象，无需手动解析
System.out.println("订单 " + evt.getOrderId() + " 状态 " + evt.getStatus());
​

预期输出 订单 order-1024 状态 CREATED。两段代码与裸字节数组版本的区别只有 Schema.JSON 这一处包装——契约的接入成本几乎为零，这是它值得默认开启的理由。

二、兼容性拦截：一次"改字段"的实战推演

现在演示契约的牙齿。产品要求订单事件加一个字段 discountAmount。开发者改了 OrderEvent 类（新增字段并赋默认值），重新部署生产者——发生了什么？沿着时序看服务端的行为：

时序里藏着这套机制的治理哲学：兼容性检查发生在注册时，不是消费时。事故从"下游半夜崩了再回滚"提前到"上游部署时就被拦下"。拦截后的正确姿势不是绕过策略，而是走演进方案——新增字段保持可缺省、删除字段分两步走（先停写再删定义）、字段类型永不原地变更。这些动作与数据库表结构迁移的心法一致，做过数据迁移的工程师会感到熟悉。

兼容策略按命名空间设置，一眼看懂全部档位：

# 查看与设置命名空间的兼容策略
$ pulsar-admin namespaces get-schema-compatibility-policy trade-order/transaction
# 输出：FULL（完全兼容）

$ pulsar-admin namespaces set-schema-compatibility-policy trade-order/transaction \
    --compatibility BACKWARD
# 常用档位：BACKWARD 新读旧 兼容 / FORWARD 旧读新 / FULL 双向 / ALWAYS 无约束
​

三、Avro 与 JSON 的选择

两种主流格式各有倾向。JSON Schema 依赖类的字段描述，写起来最轻，人类可读，适合中小规模与快速迭代；Avro 带独立的结构描述文件与注册体系，演进规则严格、序列化紧凑，适合大吞吐与跨语言强约束的场景。选择方法与选压缩算法同款思路：用变更频率、吞吐体量、语言分布三问衡量。经验值是：内部 Java 单语言的业务主题，JSON 足够；跨团队跨语言的核心管道，Avro 的严谨性值回配置成本。

本节要点回顾

• Schema 让主题带类型契约：入口校验、出口即对象；
• 兼容性检查在 Schema 注册时发生，事故拦截从下游崩前提前到上游部署时；
• 新增字段可缺省、删除字段分两步、类型永不原地改，是演进三守则；
• 兼容策略按命名空间挂档位，BACKWARD 与 FULL 是最常用两档；
• JSON 轻便适合快速迭代，Avro 严谨适合跨语言大吞吐。

第 5 章收拢：发送、接收、旁听、契约，客户端工具箱已经配齐。第 6 章驶向生产水域——部署、监控、安全与生态。