接口兼容性演化规范与避坑准则

在微服务体系中，服务发布往往是灰度逐步推进的。这意味着在很长一段时间内，新版本的服务必须能够与旧版本的客户端/服务端协同工作。Protobuf 的一大核心能力就是对向前兼容（Forward Compatibility）与向后兼容（Backward Compatibility）的原生支持。

---

1. 兼容性定义

graph LR
    subgraph 向后兼容 ["向后兼容 (Backward Compatible)"]
        NewCode["新版本服务代码"]
        OldData["旧版本客户端数据"]
        NewCode -->|能够正确解析| OldData
    end

    subgraph 向前兼容 ["向前兼容 (Forward Compatible)"]
        OldCode["旧版本服务代码"]
        NewData["新版本客户端数据"]
        OldCode -->|能够正常解析并容忍未知字段| NewData
    end

• 向后兼容：新部署的服务代码能够正确解析旧代码序列化产生的数据。
• 向前兼容：旧版本的服务代码在收到新代码生成的数据（包含新字段）时，不会崩溃，并能够安全忽略未知字段。

---

2. 字段演化核心铁律

① 绝对不能更改已有字段的编号（Tag Number）

Protobuf 二进制流中不包含字段名，全靠 Tag 标识。一旦修改了现有字段的 Tag，所有现有客户端反序列化时该字段都会丢失或错位。

② 新增字段是安全且鼓励的

• 旧版代码读取包含新字段的数据时：旧版代码不认识该 Tag，会将其作为未知字段（Unknown Fields）保留或丢弃，已有业务字段不受影响。
• 新版代码读取旧数据时：新字段不存在于旧数据中，新版代码会自动赋予其默认零值。

③ 废弃/删除字段必须使用 reserved

千万不要直接将 .proto 中的废弃字段整行删除！ 因为未来其他开发者可能会无意中重新分配同一个 Tag 编号或字段名，导致灾难性的老数据解析错乱。

正确做法：标记为 reserved：

message UserProfile {
  // 错误示范：直接删掉 2 号字段
  // string nickname = 2; [DELETED]

  // 正确示范：声明保留编号与名称，防止后续被意外复用
  reserved 2, 15, 20 to 30;
  reserved "nickname", "avatar_url";

  string user_id = 1;
  string email = 3;
}

---

3. 数据类型变更的兼容性规则

某些类型在底层采用相同的 Wire Type，因此具备一定的类型互换兼容性，但需格外小心：

变更前类型	变更后类型	兼容性评估	风险与注意事项
int32, uint32	int64, uint64	兼容	均采用 Varint 编码。但从 64 位切回 32 位会有截断（Truncation）风险
sint32	sint64	兼容	均采用 ZigZag + Varint
int32	sint32	❌ 不兼容	负数编码完全不同（一个 10 字节，一个 ZigZag 变长）
fixed32	sfixed32	兼容	均占用 4 字节，但最高符号位解析不同
string	bytes	兼容	均采用 Wire Type 2。前提是 bytes 必须包含合法的 UTF-8 编码
单值字段	repeated	⚠️ 部分兼容	如果客户端期待单值而收到 repeated，Proto3 通常会取最后一个元素；反之则放入单元素列表

---

4. 枚举（Enum）演进避坑准则

enum UserRole {
  USER_ROLE_UNSPECIFIED = 0;
  USER_ROLE_GUEST = 1;
  USER_ROLE_MEMBER = 2;
  // 灰度新加的枚举值
  USER_ROLE_ADMIN = 3;
}

1. 第 0 个枚举值永远不可修改：Proto3 强制第 0 个枚举为默认值。修改它会导致所有反序列化默认值发生漂移。
2. 处理未知枚举值：在 Proto3 中，如果旧版代码反序列化接收到了新版定义的 USER_ROLE_ADMIN (3)，它会直接保留数值 3，并在转换为整型时正确展示，但 switch-case 分支中必须具备 default 兜底保护逻辑。

---

5. 生产级契约演化最佳实践

1. 严禁修改字段语义：如果需要变更含义（例如将 price 从“元”改为“分”），请新增字段 price_in_cents = 5;，而不是原地修改。
2. 包版本隔离（Package Versioning）： 在微服务发生不可调和的重大不兼容重构时，采用包路径版本号做物理隔离：

   // 旧版本服务
   package payment.v1;
   
   // 颠覆性重构的新版本服务
   package payment.v2;
   

3. CI 自动化 Lint 与 Breaking Change 检查： 集成现代 Protobuf 工具（如 buf breaking），在 Git Commit / Merge Request 时自动拦截任何破坏向后兼容性的契约修改。