4. 行情数据Schema设计原则

行情数据Schema不是一次性写完就冻结的接口契约，而是随交易所规则、品种扩容、字段语义细化而持续演进的“活文档”。设计阶段若只考虑当下字段，后续每次新增字段都可能引发下游解析失败、字段错位甚至静默丢数。本节围绕可扩展性、向后兼容、向前兼容、字段命名规范、类型选择与版本标识策略六项原则展开，帮助你在Schema设计源头降低演进成本。

一、核心原理：兼容性的两个方向

兼容性讨论必须区分方向。向后兼容（Backward Compatibility）指新版本Schema能够被旧消费者正确读取，即“新写旧读”；向前兼容（Forward Compatibility）指旧版本Schema产生的数据能够被新消费者正确读取，即“旧写新读”。行情分发链路中，生产者升级往往快于消费者，因此向前兼容是更常被忽视却更致命的一环。

下图展示同一份行情Schema在三个版本迭代中，字段增删对上下游兼容性的影响路径。绿色路径表示兼容，红色路径表示破坏。

二、方法流程：六项原则的落地检查

将原则转化为可执行的Schema评审清单，建议按以下顺序逐项确认：

1. 可扩展性优先：预留扩展位，避免把字段写死为固定枚举。例如行情类型不要只定义“股票/期货”，而应保留字符串编码空间。
2. 字段命名规范：统一采用小写下划线或小驼峰，全链路一致；时间字段统一后缀 _ts 并明确时区与精度。
3. 类型选择：价格、数量优先使用定点数或字符串表示，避免浮点精度丢失；布尔与枚举区分对待。
4. 版本标识：每条消息携带 schema_version，消费者据此选择解析分支。
5. 兼容性验证：用旧消费者解析新数据、新消费者解析旧数据，双向回归。
6. 废弃策略：字段废弃先标记 deprecated，保留至少一个发布周期后再移除。

三、案例场景：一次价格类型变更的复盘

某行情网关将 price 从 float64 改为 int64（单位由元改为分），版本号仅从 v2 升到 v2.1。结果下游风控系统按元解析，价格被放大100倍，触发大量误报。根因有三：一是类型变更属于 MAJOR 级破坏性变更，却只升了 MINOR；二是未做双写过渡；三是消费者未校验 schema_version。

{
  "schema_version": "2.1.0",
  "symbol": "BTCUSDT",
  "price": 6850000,        // 单位：分，旧消费者按元解析 → 68500 元
  "price_unit": "cent",    // 新增单位字段，但旧消费者忽略
  "ts": 1735689600000
}

四、误区与修正

• 误区一：新增字段一定兼容。若消费者使用严格模式（如 Avro 的 strict 或 Protobuf 的 required），新增字段仍可能报错。应优先使用可选字段。
• 误区二：版本号放在 topic 名即可。topic 名无法表达单条消息的版本，且不利于回放历史数据。版本应内嵌消息体。
• 误区三：向前兼容不重要。行情回放、历史数据重算场景中，新消费者读取旧数据是常态，必须容忍字段缺失。
• 误区四：字段命名可随意。命名不一致会导致映射层反复出错，建议在Schema注册中心统一校验。