Thrift 迁 Protobuf:IDL、生成物与传输要分轨

Hello,我是小兔大白糖。 评审会上常有人说:「换 Protobuf / gRPC 呗,IDL 改完就行。」——语法改完只是开头。贵的是字段编号与枚举映射、生成物全量替换、客户端与服务端传输协议成对对齐,以及旧 Thrift 调用方怎么过窗口。写成这篇,给要做 RPC 契约迁移调研与选型的初中级后端同学:不是某仓库的文件清单,而是业界可复述的心智模型。
说明:文中分层名、切流模式名是分析框架,不是某厂 SLA。Apache Thrift、Protocol Buffers、gRPC 等只作公开生态举例;示例与伪流程均为教学脱敏示意,不写厂商官方内幕。实时帧侧的 Protobuf 信封另见 /blog/websocket_protobuf_framework/——本文主线是 服务间 RPC IDL / 传输切流。
估计阅读时间:10 分钟
目录
为什么现在要关心
硬规则先钉:IDL 迁移是多层合同;只改 .thrift → .proto 语法,不等于调用链能通。
现场里常见的误伤,几乎都来自把五件事当成「换个文件扩展名」:
| 你看到的现象 | 常见真相 |
|---|---|
| 「同名同义,编号随便排」 | field number / enum 值一变,旧二进制语义就歪;兼容性是谎言 |
| 半仓库旧 gen、半仓库新 stub | 生成物是制品;混 import 比编译错误更难查 |
| 服务端已上 gRPC,客户端仍打 Thrift 传输(如 framed) | 传输层是另一份合同;一端改一端未改 → 全挂 |
| 业务编译过了,默认值行为怪 | proto3 枚举 0 常作 unspecified 哨兵;旧 Thrift 默认语义要对表 |
| 开发机绿、CI / 镜像红 | 没 pin protoc 与插件;生成物入库却版本漂移 |
五条可复述硬规则(删掉比喻也能带走):
- 契约先于生成物:重定 field number / enum;不要假设「同名同义」。
- 生成代码是制品,不是手改源:删旧 gen、用新工具链重生;业务只适配类型与枚举访问差异。
- 传输层单独合同:Thrift 传输(公开概念里常见如
TFramedTransport一类)与 gRPC / HTTP2 不是改 IDL 就自动切换;客户端与服务端协议要成对改。 - 切流要双轨或强同步发版:只升服务端、旧客户端仍打旧协议 → 窗口内全挂。
- 构建与镜像也要跟:编译器 / 插件版本 pin;CI 与镜像缺工具链会暗崩。
心智模型:合同换章 + 邮路换轨
先记住三层:IDL 是合同正文,生成 stub 是格式文本,传输协议是邮路——合同换了,邮路可能仍要另改。
| 类比 | 对应概念 | 硬规则直觉 |
|---|---|---|
| 合同正文 | IDL(.thrift / .proto) | 条款编号 ≈ field number;改编号等于改合同条款号 |
| 律师楼打出来的格式文本 | 生成 stub / codec | 可再生产品;手改 gen 等于改打印件却不改合同 |
| 邮路(平邮 vs 专线) | 传输协议(Thrift 栈 vs gRPC/HTTP2 等) | 合同换章 ≠ 邮路自动换轨;两端要同时认同一条路 |
类比局限一句说清:合同 / 邮路解释「契约、生成物、传输怎么分工」;解释不了服务发现、负载均衡、鉴权挂载点——那些仍要按基础设施单独设计。
和实时通道那篇的分工:那边谈的是「管道(WebSocket)+ 清单(schema)+ 货物(帧)」;这边谈的是「服务间 RPC 换合同 + 是否换邮路」。两者都用 Protobuf 当清单时,不要把「帧上了 Protobuf」当成「RPC 也迁完了」——合同面不同。
问题空间:五层,不是改扩展名
每层有独立翻车面;评审时按层勾,比按「迁移进度百分比」可靠。
| 层 | 你在改什么 | 典型翻车 |
|---|---|---|
| IDL | 语法、field number、package / 语言选项(如 go_package) | 编号冲突;「同名」当兼容 |
| 生成物 | stub / codec 目录与 import | 半旧半新;手改 gen「临时修」 |
| 运行时协议 | Thrift 传输 vs gRPC(或其它) | 一端切一端未切 |
| 业务适配 | 枚举访问、空值 / 指针习惯、流式 API 差异 | 编译过、语义歪 |
| 工具链 | 旧 IDL 编译器 vs protoc + 插件 | 本地绿、流水线 / 镜像红 |
公开生态里,Thrift 与 Protobuf / gRPC 常被并列讨论,但它们不是「换语法糖」关系:一边是 IDL + 多种传输组合;一边常见是 .proto + gRPC(HTTP/2)这一条主流车道。选型时把「要不要换邮路」单独写进评审,避免默认「上了 proto 就等于上了 gRPC」——其它 Protobuf RPC 栈也存在,本文只按主流车道举例。
业界切流模式对照
调研默认:能控全部调用方用同发;多团队存量用双协议窗口,并写死关闸日。
| 模式 | 做法 | 优点 | 代价 / 边界 |
|---|---|---|---|
| A. 大爆炸同发 | 调用方与被调方同一发布窗口切 IDL + 传输 | 日历短;无长期双栈 | 协调成本高;窗口失败回滚面大 |
| B. 双协议窗口 | 服务端短时双栈、旁路新端口,或网关按协议分流;客户端分批切 | 多团队可错峰;风险可观测(旧协议占比) | 运维双栈;必须有关闸日,否则永久两套 |
| C. 新服务只用新 IDL | 旧服务冻结旧契约;新边界只走新栈 | 旧系统少动 | 长期两套契约与两套工具链;边界网关变复杂 |
实践上很少「只选一个标签」:常见是 核心链路 B + 新边界 C;能锁日历的小集群用 A。双栈形态(同端口探测 / 新端口 / 网关分流)是实现细节,评审先锁「窗口 + 关闸」,再选形态。
代价先说清:B 越久 → 双栈成本、测试矩阵、值班认知负荷越高。稳的是有关闸的窗口,不是无限双轨。
可复述迁移清单
按漏斗顺序做:IDL → 生成物 → 业务适配 → 传输成对 → 工具链 pin → 切流与关闸;漏一层,后面的「绿」都不可信。
教学向清单(脱敏,非某仓库脚本):
1. rewrite IDL(新 field number / enum;语言 package 选项)
2. regenerate all stubs;删除旧 gen 树,禁止手改
3. adapt 业务调用点(枚举、空值、流式 API)
4. align transport:服务端 AND 客户端成对切换
5. pin protoc + 插件于 CI / 镜像
6. dual-run 或 lockstep 发版;盯旧协议流量占比
7. gate:窗口结束后关旧协议入口枚举迁移多钉一句:proto3 习惯把 0 留作 unspecified 哨兵——从 Thrift 迁过来时,用一张显式映射表核对旧默认值 / 零值语义,不要靠「名字像就行」。若团队仍用 proto2 或自定义零值约定,以本仓库/语言选项为准对表即可。
字段演进与实时帧同一纪律(公开可核对的 Protobuf 兼容常识):新增用新号;废弃保留号一段时间;不要复用旧字段号装新语义。 RPC 契约面与 WS 帧面都适用;细节心智可对照 /blog/websocket_protobuf_framework/。
反模式
从架构视角看,下面几条会把「换 IDL」重新揉成一次不可回滚的全站事故。
-
只改服务端生成物
旧客户端仍打旧协议或旧编号语义 → 窗口内全挂。传输与 stub 都要成对想。 -
手改 gen 目录「临时修」
下一轮 regenerate 冲掉;或一人本地版本漂移。生成物是制品,业务适配写在业务侧。 -
字段编号随意重排当无事
二进制兼容靠编号,不靠字段名。重排 = 换合同条款号。 -
传输协议与 IDL 混为一谈
「已经写.proto」不等于「对端已走 gRPC」。邮路要单独验收(抓包 / 指标 / 协议探测)。 -
无关闸的永久双栈
双协议窗口的代价会变成永久税。关闸日写进迁移合同,并用旧协议流量指标验收。 -
CI 不装编译器,靠开发机生成物入库
本地绿、流水线红;插件小版本一漂,全员「偶发编不过」。pin 版本,镜像与 CI 同源。
选型结论
- 先拆三层合同:IDL(条款编号)≠ 生成 stub(制品)≠ 传输(邮路);再叠业务适配与工具链两层排障面。
- 切流模式:能锁调用方用 A 同发;多团队存量默认 B 双协议窗口 + 关闸;新边界可 C 只走新栈,并接受长期两套契约的税。
- 可复述漏斗:重写 IDL → 全量重生 → 适配调用点 → 传输成对 → pin 工具链 → 观测旧协议占比 → 关闸。
- 枚举与零值要显式映射表;proto3
0哨兵习惯与旧默认语义必须对表。 - 禁止:只升一端、手改 gen、编号当儿戏、IDL 与传输混谈、永久双栈、生成物靠人肉入库。
相关阅读(帧侧 Protobuf,非本文主线):/blog/websocket_protobuf_framework/。