数据帧与协议契约

Category

networking / 协议契约。节点定位：把包体设计、演进纪律与异常处理当成客户端、服务端、工具链之间的长期契约来治理。

Definition

协议包体不只是字节格式，它还是客户端、服务端、接入层、工具链、灰度版本和后台系统之间的长期契约。很多线上事故并不是网络断了，而是不同版本、不同模块、不同平台对同一条消息出现了不同理解。

为什么协议问题总会在后期变重

协议在项目初期通常看起来很简单：

• 定一个消息号。
• 放几个字段。
• 本地联调能通。

但游戏项目的协议几乎一定会持续演化。你迟早会遇到：

• 新字段增加。
• 旧字段废弃。
• 枚举扩展。
• 压缩、加密或包头策略变化。
• 热更新和渠道包共存。
• 客户端与服务端版本并不完全同步。

如果这时协议没有契约意识，系统就只能依赖一个很脆弱的假设：所有参与方永远一起升级，而且永远不会误解字段。

Problem

协议契约真正包含什么

一条成熟的协议契约，通常不只是“字段长什么样”，而应该至少包含：

• 消息编号或消息类型的业务语义。
• 请求和响应结构定义。
• 字段含义、默认值和可选规则。
• 枚举扩展规则。
• 错误码语义。
• 兼容窗口和版本协商方式。
• 异常包与非法值处理方式。

也就是说，协议契约真正定义的是：不同参与方如何对同一条消息保持一致理解。

为什么游戏协议更难治理

游戏协议的参与方往往远多于普通接口系统：

• 多个平台客户端。
• 接入层和网关。
• 房间服、世界服、活动服等多个后端。
• 自动化测试、录包回放和调试工具。
• GM 或运营后台。

参与方一多，协议一旦不稳，代价就不只是一个接口报错，而是整条主链路进入兼容与回归泥潭。

包体设计时真正要关心什么

1. 外层包头要稳定

大多数项目都会有自己的外层包头，用来承载：

• 消息号或路由键。
• 会话标识。
• 序号或请求 ID。
• 压缩标记。
• 加密标记。
• 长度字段。

包头最重要的不是复杂，而是稳定。它一旦频繁变化，接入层、录包工具、调试工具和异常包处理逻辑都会跟着抖。

2. 业务载荷要有明确语义

载荷部分通常才是 protobuf、自定义二进制结构或其他序列化格式的主体。这里最重要的不是语法优不优雅，而是：

• 字段是否有明确语义。
• 默认值是否安全。
• 新旧版本遇到未知字段时是否还能工作。
• 删除字段后旧逻辑是否还能稳住。

3. 错误返回必须分层

很多协议问题，其实出在错误返回不成体系。更稳妥的做法通常是区分：

• 协议层错误。
• 会话层错误。
• 业务层错误。

否则客户端收到一个失败结果时，根本不知道该重连、重试、重登，还是只是提示玩家。

协议演进最怕什么

协议演进最怕的不是字段变多，而是无规则变化。典型灾难包括：

• 服务端默认新字段一定存在，旧客户端却根本不发。
• 枚举新增值后，旧端把它当非法值处理。
• 某字段从可选变必填，却没有兼容窗口。
• 同一消息号在不同版本里被赋予了不同业务含义。

这些问题在全量同版本环境里可能不明显，一旦进入灰度、多端并行和渠道审核延迟环境，就很容易出事故。

协议治理不是序列化格式选型题

选 protobuf、flatbuffers、自定义二进制结构都可以，真正决定系统寿命的往往不是格式本身，而是有没有治理规则。比较稳妥的治理通常包括：

• 明确字段新增和废弃规则。
• 不轻易复用旧消息号。
• 保留兼容窗口。
• 协议变更伴随说明和测试。
• 自动检查新旧协议差异。

如果这些规则不存在，哪怕格式本身再成熟，协议也会慢慢烂掉。

多版本共存时必须提前回答什么

只要项目存在：

• 灰度发布。
• 渠道审核延迟。
• 热更新。
• 不同平台不同发版节奏。

就必须提前回答：

• 客户端和服务端版本不一致时，谁先拒绝谁。
• 哪些协议必须强同步升级。
• 哪些协议可以靠默认值和兼容字段平滑过渡。
• 房间内是否允许新旧版本共存。

这类问题如果不提前写成规则，最后只能依赖“上线时大家小心一点”。

异常包和非法值不能只靠信任

游戏环境里的异常包来源很多：

• 客户端 Bug。
• 版本不兼容。
• 作弊工具篡改。
• 链路截断或错误拼包。

因此协议层必须有明确非法包处理策略，例如：

• 丢弃。
• 限流。
• 断开连接。
• 记录审计。
• 触发更高层重连或重登。

这不是安全附加题，而是稳定性治理的一部分。

常见误区

• 把协议当内部实现细节，改字段时只保证“本地联调能过”。
• 在没有版本协商和兼容窗口的情况下频繁改包体，最后把客户端、接入层和服务端一起拖进回归泥潭。
• 只盯序列化格式，不做协议治理，最终系统死在演进规则上。

数据帧设计真正要治理的，不是“字节怎么排”，而是协议作为长期契约怎样稳定演进。

实战案例：一次「新版本灰度，旧客户端全量报错」的字段变更排查

案例为教学示例（非摘自真实项目），数字经过取整简化。它把本页「协议演进最怕什么」「错误返回必须分层」「多版本共存时必须提前回答什么」用到深水区：新旧包各 5% 灰度、失败率却差两个数量级——这是灰度期协议兼容窗口的排查，也是「怎样让协议变更不把多端拖进回归泥潭」的完整展开。

背景与现象：某卡牌手游发新版本，灰度新包 5%、存量旧包 95%。灰度开始 2 小时内，旧客户端进房失败率冲到 3.8%，新包只有 0.02%；客服口径是「更新后反而进不去」。客户端报错一律是「网络异常，请重登」，重登 QPS 峰值冲到 4200，是平日的 7 倍——重登风暴反过来又挤压了登录链路。

第一步：现象与口径——先按版本分桶，再按错误分层

版本分桶口径：失败率 3.8% 全部集中在旧版本两档（上上週与上週包），新包 0.02% 与历史水位持平——问题只在版本差异，不在链路。

错误分层口径：服务端日志里这些失败分三种——71% 进房消息解析失败（协议层）、22% 收到未知枚举值断连（协议层）、7% 会话有效但业务拒绝（业务层）。而客户端把三种错误一律显示成「网络异常，请重登」，因为错误码没有分层。

抓包口径：抓新旧两包的同一条进房消息对比，同一消息号，载荷结构已经不同。

第二步：分层归因——按本页演进灾难清单逐项比对

旧端进房失败 3.8%  归因
  新字段从可选变必填，旧端不发送解析失败    71%  →  2.7 个百分点
  枚举新增值被旧端当非法值断连             22%  →  0.8 个百分点
  错误码不分层放大成重登风暴                7%  →  0.3 个百分点

逐项比对：服务端在进房消息里新增了 season 字段并按必填解析，旧端根本不发这个字段，71% 的失败直接命中本页灾难清单第一条「服务端默认新字段一定存在，旧客户端却根本不发」；同一次发版还扩展了房间类型枚举，旧端把新值当非法值断连，命中第二条。

第三步：根因——无兼容窗口、无版本协商、错误码不分层

这次发版同时改了字段必填性和枚举值，两个变更都走「本地联调能过」就上线：没有兼容窗口，没有版本协商规则，错误返回也不分协议层、会话层、业务层。三个缺口叠在一起，一次本可以平滑过渡的字段新增，变成了旧端断连加重登风暴。

第四步：处置与回填——先止血，再把规则入档

1. 止血：回滚进房消息的必填性，season 退回可选并给安全默认值，枚举新值对旧端改走旧消息号下发——30 分钟内失败率回落到 0.05%。
2. 错误码三层：协议层（解析失败，走重连）、会话层（会话失效，走重登）、业务层（业务拒绝，走界面提示），客户端按层决定动作，不再一律重登。
3. 规则入档：字段新增默认可选、废弃先标记后删除、枚举扩展必须带旧端处理策略、兼容窗口最少一个版本周期，写进协议变更检查单，每次协议 PR 附新旧差异对比测试。

复核账：旧端进房失败率 3.8% → 0.05%；重登 QPS 峰值 4200 → 300；因断连产生的客服工单清零；下一次发版同口径复查，兼容窗口内两档旧包失败率均低于 0.1%。

回填清单：

回填项	动作	回填处
字段新增废弃规则	新增默认可选给安全默认值；废弃先标记后删除，删除前查旧端引用	协议契约真正包含什么
错误码三层	协议层/会话层/业务层分别编码，客户端按层决定重连、重试、重登还是提示	错误返回必须分层
兼容窗口与版本协商	最少一个版本周期的兼容窗口；多版本共存时谁先拒绝谁，提前写成规则	多版本共存时必须提前回答什么
异常包处理策略	非法值按丢弃、限流、断连、审计分级处理，不再一律断连	异常包和非法值不能只靠信任

案例的三个教训

1. 协议是长期契约，改字段先问旧版本怎么办。「本地联调能过」验证的是同版本环境，灰度一开就是多版本环境——必填性变更和枚举扩展都要带旧端策略。
2. 错误码不分层，客户端只能一律重登，重登风暴比原故障更伤。本案 7% 的业务层错误被放大成 7 倍重登 QPS，分层错误码是止血手段，不只是体验优化。
3. 灰度期就是兼容窗口期，规则要提前写而不是「上线时大家小心一点」。字段、枚举、错误码各自的兼容规则入档成检查单，才扛得住渠道审核延迟和热更窗口叠加。

Used By

协议评审与版本灰度；多版本共存期（热更窗口、渠道审核错峰）；异常包与外挂面的字段级审查。

Related

上游：传输层选择（03）。下游：兼容性纪律（06）、版本发布（production 树）。关系链：协议契约 → 兼容策略 → 多版本灰度 → 回滚预案。

Reference

本页为工程经验归纳；Protobuf/FlatBuffers 的兼容性细则以各自官方文档为准；页内实战案例为教学示例（数字取整简化）。