WebSocket + Protobuf:一套实时消息框架怎么搭

WebSocket + Protobuf:一套实时消息框架怎么搭

Hello,我是小兔大白糖。 联调现场:聊天、typing、在线状态一多,弱网手机又卡又费电——帧里还是一长串 JSON,键名重复占带宽。写成这篇,给要把 WebSocket 长连接 + Protobuf 二进制帧 收成一套可维护实时消息框架的初中级后端同学。

说明:文中字段名、伪代码、数量级均为教学脱敏 / 示意,不是某家产品的内部协议,也不是「改完一定快 N 倍」的保证。读完带走的是心智模型与设计清单。HTTP 控制面仍常用 JSON——本文只当边界一句带过,不展开迁移。

估计阅读时间:12 分钟


目录


为什么现在要关心

实时路径最贵的不是「能推一条消息」,而是把连接生命周期、帧约定、类型分发钉成前后端同一套合同。

常见现场:

你看到的现象常见真相
弱网下聊天帧又胖又密小字段反复文本编码,键名重复;CPU 与电量一起涨
「WS 已经上 Protobuf」但抓包仍是文本连上了,帧类型 / 载荷约定没钉死
升级偶发 4xx,有人怪「握手没回 protobuf」把 HTTP 升级握手 和 长连接帧载荷 搅在一块
偶发「解出来空壳但 err==nil」用 try-Unmarshal「猜格式」——脏字节不一定报错
换了二进制,群聊仍打爆推送只改编码,没改错误扇出(业务边界见 IM 文)

本文只谈:心智模型 → 握手/帧边界 → 框架五件套 → 最小信封 → 多实例扇出边界 → 坑。 不写全站格式迁移 KPI,也不写某公司路线图。


心智模型:管道、清单与货物

先记住三层:管道是 WebSocket,货物清单是 Protobuf schema,货物是二进制帧里的字节。

类比对应概念硬规则直觉
管道WebSocket 长连接负责保活、鉴权挂载点、按连接投递;不管业务字段怎么排
货物清单.proto / 生成代码字段号、类型、兼容规则;人靠清单读懂二进制
货物一帧二进制载荷常见:二进制帧 + Protobuf;文本帧另作约定(或过渡期)
面单上的品类码信封里的 type / opcode先认类型,再按类型解 payload——别整包瞎猜
WebSocket 握手后二进制帧经编解码按 type 分发
WebSocket 握手后二进制帧经编解码按 type 分发 · 点击查看 SVG 原图

类比局限一句说清:管道/清单解释「连接与编码怎么分工」;解释不了房间态、已读语义、离线 Push——那些仍要按业务域单独设计(例如 /blog/im_chat_room_message_design/)。


精确定义:握手 ≠ 帧载荷

WebSocket 升级握手仍是 HTTP;Protobuf(或 JSON)谈的是连上之后帧里怎么装。

层发生时机你在约定什么典型失败形态
握手(Upgrade)连接建立前状态码、鉴权头 / Cookie / 查询参数、失败时的错误体401/403/4xx;与「帧是不是 Protobuf」无关
帧载荷长连接存活期间文本帧 vs 二进制帧、schema 版本、信封字段解码失败、类型未知、版本不兼容

再钉三条硬边界:

  1. 握手 ≠ 帧。
    不要写成「某个 connect HTTP 接口返回了 protobuf,就算实时通道上了 Protobuf」。升级失败回的是 HTTP 语义;载荷格式是连上之后的事。

  2. 帧类型与编码要显式约定。
    常见教学约定:二进制帧 ≈ Protobuf;文本帧 ≈ JSON(若仍保留)。用帧类型、连接级协商、或帧头 opcode——禁止靠「先 Unmarshal,成功就当 Protobuf」探测(见常见坑)。

  3. 控制面 JSON 完全合法。
    CRUD、配置、运营后台继续 HTTP+JSON,不等于技术落后——本文不展开那条车道。

HTTP 业务成败怎么用响应信封表达,见 /blog/api_response_envelope/;实时帧上的「业务失败」通常走信封里的错误字段或独立错误 type,别和 HTTP 状态码混谈。


框架五件套

一套可维护的实时二进制通道,至少钉这五块;缺一块后面都会用「临时 if」补洞。

件套职责钉死什么
1. Schema消息形状与字段号.proto(或等价 IDL);生成多端代码;字段号慎改、慎复用
2. Codec字节 ↔ 结构体入站:帧 → 信封 → 按 type 解 payload;出站对称;失败要有明确错误,不静默空壳
3. Router按类型分发type / opcode → handler;未知类型拒绝或进死信策略(团队定一种)
4. Heartbeat保活与死连接回收ping/pong 或业务心跳间隔、超时踢线、谁先发
5. Version演进与回退连接参数或首帧 schema_version;旧客户端是否允许旧帧;下线条件

教学向体积 / CPU 数量级(示意,必须自行压测;禁止当 SLA):

指标(示意)文本 JSON 帧Protobuf 二进制帧怎么读
同结构小消息体积基准 1×常见约 0.3×~0.8× 量级键名重复越多,二进制越占优
编解码 CPU基准 1×常见更快,但波动看实现以你仓库同一条业务消息的基准为准
端到端延迟往往不是主矛盾弱网 + 高扇出时更明显先量带宽与手机耗电

「稳赚 3~10 倍」是营销区间,本文不保证。数字没进你们自己的基准测试,就没有资格进评审。


最小信封设计

先定「外层信封」,再往 payload 里塞具体业务消息——和 HTTP 响应信封同一思路,只是载体换成 WS 帧。

教学字段表(不是强制 schema;字段号仅示意):

字段类型直觉含义硬边界
typeenum / int消息品类(chat / typing / ack / error…)先读 type,再选 payload 消息类型
payloadbytes内层业务 Protobuf禁止「整帧当某一种业务消息硬解」
schema_versionint信封或连接级版本与业务消息字段演进分开想更清晰
request_idstring(可选)请求-响应关联回执、错误对齐用
tsint64(可选)发送方时间戳只作辅助;排序真相常在服务端序号

分发伪代码(教学脱敏,合计 ≤10 行):

frame = read_binary_frame()
env   = decode_Envelope(frame)          # 失败 → 关连接或回 error type
msg   = decode_by_type(env.type, env.payload)
dispatch(env.type, msg)                 # 未知 type → 约定拒绝策略

内层业务消息各自一份 schema(聊天正文、typing、在线状态…)。版本演进:新增字段用新号;废弃字段保留号一段时间;不要复用旧字段号装新语义。双端生成流水线要进同一条 CI,否则「一端升 schema、一端还在猜」会变成生产事故。


扇出与多实例边界

单机连上能推,不等于多实例下「对的人」都能收到;编码换紧凑,救不了错误扇出。

边界单实例直觉多实例必须补什么
连接亲和用户连在本进程连接表或网关路由;广播不能假设「人都在本机」
房间/主题订阅内存 map:room → conns跨实例 pub/sub(或等价总线)再落到持有连接的节点
在线 vs 离线WS 推失败就结束?在线走 WS;离线走 Push / 补拉——分状态追踪
扇出基数一对一还好群 typing、群已读若错误全员推,换 Protobuf 也打爆(见 IM 文)

合同建议写进评审:

  1. WS 只保证「持有该连接的节点」投递;跨节点靠总线,不靠「多发几次碰运气」。
  2. 业务成功 ≠ 推送成功;落库与投递分状态,客户端要有补拉。
  3. 谁该收到由领域规则定(房间成员、屏蔽、免打扰),不由「帧是不是二进制」定。

常见坑

  1. 握手与帧搅在一起
    升级失败查 HTTP 状态与鉴权;帧解码失败查 codec / 版本 / 帧类型。别让排障开错抽屉。

  2. try-Unmarshal 探测格式(禁止当推荐)
    「Unmarshal 没报错 ⇒ 一定是合法 Protobuf」不可靠:截断包、脏字节、甚至部分文本,都可能出现空壳或乱填。用显式帧类型、魔数、opcode 或连接级协商结果。

  3. 没有信封,整帧当业务消息
    新加一种消息类型就要改「唯一入口」的硬解逻辑;未知类型无法优雅拒绝。

  4. 字段号复用 / 静默改语义
    旧客户端把新语义解成旧字段,数据看起来「能通」其实已脏。演进靠新号 + 弃用窗口。

  5. 只改编码、不改扇出
    群已读、全员 typing 照搬一对一扇出——体积小了,推送量照样炸。

  6. 心跳与业务帧抢同一条「随便解析」路径
    ping/pong 或心跳 type 要进路由表;超时踢线规则写清,避免半死连接占满额度。

  7. 调试成本低估
    不能再「复制 JSON 给前端」。要准备解码脚本、抓包插件或内建 debug 文本通道(若开,必须鉴权且默认关)。


小结

  1. 三层分工:管道 = WS;清单 = schema;货物 = 二进制帧。
  2. 握手 ≠ 帧载荷:Upgrade 仍是 HTTP;Protobuf 谈的是连上之后怎么装。
  3. 五件套:Schema / Codec / Router / Heartbeat / Version——缺一就会用临时探测补洞。
  4. 最小信封:type + payload(+ 版本 / 关联 id);先分发再解业务。
  5. 显式约定,禁止 try-Unmarshal 猜格式。
  6. 多实例扇出与「谁该收到」是业务/基础设施边界;换编码不自动修复。

帧类型命名、鉴权挂在握手还是首帧、媒体类型名(若 HTTP 旁路也要二进制)由团队写进约定;性能数字仅为数量级示意,以你们基准测试为准。

下一步:挑一条真实高频 WS 消息做体积与编解码基准 → 定信封字段与未知 type 策略 → 再补心跳与多实例 pub/sub。相关阅读:/blog/im_chat_room_message_design/、/blog/api_response_envelope/。