
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——别整包瞎猜 |
类比局限一句说清:管道/清单解释「连接与编码怎么分工」;解释不了房间态、已读语义、离线 Push——那些仍要按业务域单独设计(例如 /blog/im_chat_room_message_design/)。
精确定义:握手 ≠ 帧载荷
WebSocket 升级握手仍是 HTTP;Protobuf(或 JSON)谈的是连上之后帧里怎么装。
| 层 | 发生时机 | 你在约定什么 | 典型失败形态 |
|---|---|---|---|
| 握手(Upgrade) | 连接建立前 | 状态码、鉴权头 / Cookie / 查询参数、失败时的错误体 | 401/403/4xx;与「帧是不是 Protobuf」无关 |
| 帧载荷 | 长连接存活期间 | 文本帧 vs 二进制帧、schema 版本、信封字段 | 解码失败、类型未知、版本不兼容 |
再钉三条硬边界:
-
握手 ≠ 帧。
不要写成「某个 connect HTTP 接口返回了 protobuf,就算实时通道上了 Protobuf」。升级失败回的是 HTTP 语义;载荷格式是连上之后的事。 -
帧类型与编码要显式约定。
常见教学约定:二进制帧 ≈ Protobuf;文本帧 ≈ JSON(若仍保留)。用帧类型、连接级协商、或帧头 opcode——禁止靠「先Unmarshal,成功就当 Protobuf」探测(见常见坑)。 -
控制面 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;字段号仅示意):
| 字段 | 类型直觉 | 含义 | 硬边界 |
|---|---|---|---|
type | enum / int | 消息品类(chat / typing / ack / error…) | 先读 type,再选 payload 消息类型 |
payload | bytes | 内层业务 Protobuf | 禁止「整帧当某一种业务消息硬解」 |
schema_version | int | 信封或连接级版本 | 与业务消息字段演进分开想更清晰 |
request_id | string(可选) | 请求-响应关联 | 回执、错误对齐用 |
ts | int64(可选) | 发送方时间戳 | 只作辅助;排序真相常在服务端序号 |
分发伪代码(教学脱敏,合计 ≤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 文) |
合同建议写进评审:
- WS 只保证「持有该连接的节点」投递;跨节点靠总线,不靠「多发几次碰运气」。
- 业务成功 ≠ 推送成功;落库与投递分状态,客户端要有补拉。
- 谁该收到由领域规则定(房间成员、屏蔽、免打扰),不由「帧是不是二进制」定。
常见坑
-
握手与帧搅在一起
升级失败查 HTTP 状态与鉴权;帧解码失败查 codec / 版本 / 帧类型。别让排障开错抽屉。 -
try-Unmarshal 探测格式(禁止当推荐)
「Unmarshal没报错 ⇒ 一定是合法 Protobuf」不可靠:截断包、脏字节、甚至部分文本,都可能出现空壳或乱填。用显式帧类型、魔数、opcode 或连接级协商结果。 -
没有信封,整帧当业务消息
新加一种消息类型就要改「唯一入口」的硬解逻辑;未知类型无法优雅拒绝。 -
字段号复用 / 静默改语义
旧客户端把新语义解成旧字段,数据看起来「能通」其实已脏。演进靠新号 + 弃用窗口。 -
只改编码、不改扇出
群已读、全员 typing 照搬一对一扇出——体积小了,推送量照样炸。 -
心跳与业务帧抢同一条「随便解析」路径
ping/pong 或心跳 type 要进路由表;超时踢线规则写清,避免半死连接占满额度。 -
调试成本低估
不能再「复制 JSON 给前端」。要准备解码脚本、抓包插件或内建 debug 文本通道(若开,必须鉴权且默认关)。
小结
- 三层分工:管道 = WS;清单 = schema;货物 = 二进制帧。
- 握手 ≠ 帧载荷:Upgrade 仍是 HTTP;Protobuf 谈的是连上之后怎么装。
- 五件套:Schema / Codec / Router / Heartbeat / Version——缺一就会用临时探测补洞。
- 最小信封:
type+payload(+ 版本 / 关联 id);先分发再解业务。 - 显式约定,禁止 try-Unmarshal 猜格式。
- 多实例扇出与「谁该收到」是业务/基础设施边界;换编码不自动修复。
帧类型命名、鉴权挂在握手还是首帧、媒体类型名(若 HTTP 旁路也要二进制)由团队写进约定;性能数字仅为数量级示意,以你们基准测试为准。
下一步:挑一条真实高频 WS 消息做体积与编解码基准 → 定信封字段与未知 type 策略 → 再补心跳与多实例 pub/sub。相关阅读:/blog/im_chat_room_message_design/、/blog/api_response_envelope/。