跳到主要内容

Payload 与 Schema

Payload Codec 定义 Payload 的编码方式，Schema 定义 Payload 的结构语义

默认策略​

消息类别默认 Payload Codec
ACKJSON
ErrorJSON
OperationJSON，具体 Operation 可覆盖
Flow 控制JSON
Flow Data由具体 Flow 定义
HeartbeatJSON
RecoveryJSON
协议层 EventJSON

协议控制类 Payload 默认使用 JSON。高频 Flow Data 可使用 Raw Binary，具体由接口定义章节声明

Schema 来源​

Operation 的 Schema 由具体 Operation 定义

Flow Data 的 Schema 来自 FlowContext。接收端通过 channel_id + flow_epoch 查询 FlowContext，不应依赖 Payload 自报 Schema

解码错误​

接收端遇到 Payload 错误时，应返回 Error 或丢弃消息

常见错误码：

  • UNSUPPORTED_PAYLOAD_CODEC；
  • PAYLOAD_LENGTH_INVALID；
  • PAYLOAD_DECODE_FAILED；
  • PAYLOAD_SCHEMA_MISMATCH；
  • PAYLOAD_REQUIRED_FIELD_MISSING；

若错误发生在 FLOW_DATA 上，接收端必须按 Flow 策略丢弃该消息、关闭 Flow 或发送协议层 Event

Raw Binary​

Raw Binary Payload 的结构由具体 Flow 或 Operation 定义。当前 Raw Binary 文档中的结构默认遵循以下规则：

  • 字段按文档表格顺序连续存放；
  • 多字节整数统一使用 Little Endian 编码；
  • float32 与 float64 统一使用 IEEE 754 二进制浮点格式，并按 Little Endian 编码；
  • 字段之间不存在隐式 Padding；
  • C、C++、Rust 示例只用于描述字段布局，跨端序列化时仍必须按 Little Endian 写入；
  • 保留字段必须写 0；
  • 接收端应校验 Payload Length；
  • 变长数组长度必须由显式字段决定；

Schema 稳定性​

Schema 名称属于 FlowContext 的一部分。若 Raw Binary 字段顺序、字段类型、单位或长度规则发生不兼容变化，必须使用新的 Schema 名称或显式 Schema Version，不能在原有 Schema 下静默改变 Wire Format