接口演进与兼容：字段演进、版本策略与灰度
线上跑着几十个服务的第一个客户端时，接口定义就已经不能随便改了。protobuf 的兼容性来自字段编号而不是字段名，所以「改一个名字」和「换一个编号」的后果完全不同：前者无感，后者是线上事故。这一章给可执行的兼容规则、破坏性变更的处理流程，以及新旧版本共存的灰度方法。
先分清两种兼容
| 方向 | 含义 | 典型场景 |
|---|---|---|
| 向后兼容（backward） | 新代码能读旧数据 | 服务端升级，老客户端还在发请求 |
| 向前兼容（forward） | 旧代码能读新数据 | 客户端还没升级，服务端已经发了新字段 |
| 破坏性变更 | 两边都读不了 | 改编号、改类型、删必用字段、改语义 |
规则的目标是让服务端先发布、客户端慢慢升级：新增永远安全，修改必须小心，删除要走流程。语义变更（字段含义变了但名字类型没变）是最阴的破坏性变更，代码检查工具抓不到，只能靠 review 与文档。
字段演进规则
| 动作 | 是否安全 | 做法 |
|---|---|---|
| 新增字段 | 安全 | 用从未用过的新编号，旧端会忽略未知字段 |
| 重命名字段 | 安全 | 编号不变即可；想改 JSON 名用 json_name |
| 删除字段 | 谨慎 | 先 reserved 编号与名字，再从代码里移除 |
| 复用已删编号 | 禁止 | 老数据里那个编号的旧值会被新字段当成有效值读进来 |
| 改字段类型 | 多数不安全 | int32→int64 尚可，string→bytes、数值→字符串直接崩 |
| 改字段语义 | 破坏性 | 例如 status 从「已支付」变成「已发货」，必须换新字段 |
改 repeated ⇄ 标量 | 破坏性 | 编码格式不同，不要试 |
message User {
reserved 3, 7 to 9; // 已删除的编号，永久封存
reserved "old_phone", "legacy_tag"; // 同时封存名字，防后来者复用
int64 id = 1;
string nickname = 2;
optional string phone = 10; // 新增：给默认值语义留余地
}
reserved 是唯一能防止后人踩坑的机制：只写注释没人看，写了 reserved 编译期就报错。新增字段一律设成「零值即默认」的语义：int32 默认 0、string 默认空串、bool 默认 false——如果业务上「0」和「未设置」含义不同，就必须加一个信封字段或用 optional。
oneof 与 optional 的坑
| 构造 | 行为 | 坑 |
|---|---|---|
oneof 中设一个字段 | 自动清空同组其它字段 | 客户端只想「部分更新」，结果把别的字段抹成未设置 |
oneof 读取 | GetXxx() 返回对应字段或零值 | 用 switch x.(type) 或 WhichOneof 判断，别用零值判断 |
proto3 optional | 生成指针字段，可区分「未设置」与「零值」 | 字段编号照样占坑，删除时仍要 reserved |
optional 与 oneof 混用 | optional 本质是单字段 oneof | 序列化体积与普通字段一致，别担心性能 |
| 在 oneof 里删字段 | 破坏性 | 编号要 reserved，且不能把编号移出 oneof 继续用 |
需要「字段级部分更新」时，推荐显式用 google.protobuf.FieldMask 或一个 repeated string update_fields，比靠 oneof 猜意图更清楚。
枚举演进
- 第一个枚举值必须是 0，且语义为「未指定」（
ENUM_UNSPECIFIED），这是 proto3 的硬性要求。 - 新增枚举值安全；删除或复用枚举数字不安全，同样用
reserved封存。 - 服务端收到未知枚举值时，proto3 会保留原始数字（Go 里读成整型值，
String()返回数字），所以判定要写default分支，不要假设取值只有已知几种。 - 枚举前缀建议与枚举名一致（
ORDER_STATUS_PAID），避免不同枚举的同名值在 C++/Java 里冲突。
版本策略
| 策略 | 做法 | 适用 |
|---|---|---|
| 无版本（只加不改） | 包名 im.v1，所有变更都做成兼容新增 | 内部服务，大多数情况够用 |
| 加版本并存 | 新增 im.v2，v1 与 v2 同时提供，v1 标废弃 | 语义发生根本变化 |
| 字段级版本 | 新字段带 _v2 后缀 | 局部变更，但会让 proto 越来越丑 |
| 服务名版本 | UserServiceV2 | 不推荐，客户端与路由都要跟着改 |
判断标准很简单：能不能用「新增字段 + 双读兼容」实现？能就别开新版本。一旦开了 v2，就要维护两套代码、两套测试、两套线上流量，删 v1 的窗口往往拖到一年以后。版本升级走三步：v2 上线并与 v1 并行 → 观测 v1 调用量降到零 → v1 服务端保留 handler 返回带提示的错误，最后再删。
灰度与兼容校验
// 服务端按 metadata 做版本分流：先只对内部流量启用新逻辑
if md, ok := metadata.FromIncomingContext(ctx); ok {
if v := md.Get("x-proto-version"); len(v) > 0 && v[0] == "v2" {
return svc.handleV2(ctx, req)
}
}
return svc.handleV1(ctx, req)
| 手段 | 用法 | 注意 |
|---|---|---|
| metadata 分流 | 客户端带 x-proto-version，服务端双实现 | 别把分流逻辑散落各处，统一放拦截器 |
| 权重灰度 | Envoy / 网关按百分比导流到新版本部署 | 新旧版本必须能互读对方的消息 |
| 影子流量 | 复制真实请求发给新版本，只比对不返回 | 注意写操作的副作用，读出后丢弃 |
| 双写双读 | 同时写新旧字段，比较一段时间 | 要有明确的收敛日期，否则永久双写 |
CI 里用 buf breaking 把兼容性检查变成门禁，比事后救火便宜得多：
buf breaking --against '.git#branch=main' # 与主干比对，有破坏性变更直接失败
buf lint # 命名与目录规范
buf generate # 生成代码，产物变更一并 review
废弃流程
| 阶段 | 服务端 | 客户端 | 观测 |
|---|---|---|---|
| 1 标记 | 字段/方法加 [deprecated = true]，文档写替代项 | 排期替换 | 记录调用方身份 |
| 2 双轨 | 新旧都能用，新字段成为首选 | 灰度切换 | 看旧字段调用量曲线 |
| 3 停用 | 旧字段不再返回有意义的值，日志给提示 | 应已切完 | 调用量应为 0 |
| 4 删除 | reserved 编号与名字，删代码 | — | 编译期保护后续使用者 |
rpc GetUserLegacy(GetUserRequest) returns (User) {
option deprecated = true; // 别直接删方法，先标废弃再等调用量归零
}
小结：protobuf 兼容性的核心是编号不复用、删除先 reserved、新增给默认语义；oneof 会互相清空、optional 才能区分未设置与零值，枚举首值必须是 0 且未知值要走 default；版本优先用「兼容新增」而不是开 v2，真要开就双版本并行并以调用量为零作为下线依据；把 buf breaking 挂进 CI，灰度按 metadata 或权重分流，废弃严格走「标记 → 双轨 → 停用 → 删除」四步。