Google Pub/Sub中Protobuf枚举新增值的兼容性报错问题及解决方案咨询

最近我遇到了一个特别困惑的问题，相信不少使用Google Pub/Sub结合Protobuf的开发者可能也会踩这个坑，特意整理出来和大家聊聊：

我在项目里同时用Protobuf做gRPC服务间通信和Pub/Sub的消息格式，之前定义了一个Refund消息，里面包含RefundStatus枚举：

message Refund {
  optional string refund_id = 1;
  // ... 其他字段
  optional RefundStatus refund_status = 12;

  enum RefundStatus {
    REFUND_STATUS_UNSPECIFIED = 0;
    REFUND_STATUS_NOT_YET_DEFINED = 1;
    REFUND_STATUS_REFUND_INITIATED = 2;
    REFUND_STATUS_REFUND_FAILED = 3;
    REFUND_STATUS_REFUNDED = 4;
  }
}

后来我给这个枚举新增了一个值：

enum RefundStatus {
  REFUND_STATUS_UNSPECIFIED = 0;
  REFUND_STATUS_NOT_YET_DEFINED = 1;
  REFUND_STATUS_REFUND_INITIATED = 2;
  REFUND_STATUS_REFUND_FAILED = 3;
  REFUND_STATUS_REFUNDED = 4;
  REFUND_STATUS_REFUND_CREATED = 5; // 新增的枚举值
}

按照我对Protobuf的理解，这种操作应该是完全前后兼容的：枚举本质是整数，老版本的客户端收到值为5的枚举时，虽然不知道对应的符号名，但会保留整数信息，不会导致崩溃，只是可读性差一点而已。但当我用Terraform更新Pub/Sub的schema时，却收到了报错：

Error: Error updating Schema "projects/<my_project>/schemas/refund": googleapi: Error 400: Compatibility checking failed to commit a schema revision for (schema="projects/<my_project>/schemas/refund"). (reason="Revision is incompatible with previous revision: . Failed with error: refund.v0.Refund.REFUND_STATUS_REFUND_CREATED = 5 is missing in refund.v0.Refund.RefundStatus).

这就让我很费解了：给Protobuf枚举新增值真的是Pub/Sub schema的破坏性变更吗？如果是这样的话，我们后续频繁更新Protobuf枚举的需求岂不是直接让Pub/Sub schema变得难以使用？难道只能先把所有枚举改成字符串，等schema稳定后再改回来？

问题根源分析 #

后来我仔细研究了Pub/Sub的schema兼容性规则，发现问题出在Pub/Sub的兼容性检查逻辑比原生Protobuf更严格：

• 原生Protobuf仅从消息的可解析性判断兼容性，新增枚举值属于向后兼容（老客户端能解析新消息）、向前兼容（新客户端能解析老消息）的操作；
• 但Pub/Sub默认的schema兼容性模式（比如COMPATIBILITY_FULL）会要求新旧版本的枚举值完全匹配——它会检查新版本中的所有枚举符号和数值，必须在旧版本中存在，反之亦然，否则就判定为不兼容。这是因为Pub/Sub的schema不仅用于消息解析，还会做元数据层面的校验，确保订阅者的schema和发布者的schema完全匹配。

可行的解决方案 #

针对这个问题，我整理了几个可行的解决办法：

1. 修改Pub/Sub Schema的兼容性模式

这是最直接的解决方案。Pub/Sub支持多种兼容性模式，我们可以把默认的严格模式改成向后兼容（BACKWARD），这样就允许新增枚举值、新增可选字段等操作：

• 在Terraform的google_pubsub_schema资源中，添加compatibility_mode = "BACKWARD"配置；
• 向后兼容模式的规则是：老版本的订阅者能够正确解析新版本的消息，这完全符合我们新增枚举值的场景——老客户端收到未知枚举值时，会保留整数信息，不会崩溃。

2. 提前为枚举预留备用值

如果必须保持严格的兼容性模式，可以在初始定义枚举时就预留一些备用的数值，比如：

enum RefundStatus {
  REFUND_STATUS_UNSPECIFIED = 0;
  REFUND_STATUS_NOT_YET_DEFINED = 1;
  REFUND_STATUS_REFUND_INITIATED = 2;
  REFUND_STATUS_REFUND_FAILED = 3;
  REFUND_STATUS_REFUNDED = 4;
  REFUND_STATUS_RESERVED_5 = 5; // 预留值
  REFUND_STATUS_RESERVED_6 = 6; // 预留值
}

后续需要新增枚举值时，直接修改预留值的符号名（比如把REFUND_STATUS_RESERVED_5改成REFUND_STATUS_REFUND_CREATED），因为数值没有变化，Pub/Sub会认为这是兼容的变更。不过要注意，Protobuf不建议修改已有枚举值的符号名，所以这个方法适合提前规划的场景。

3. 暂时用字符串替代枚举（不推荐）

如果以上两种方式都不适用，只能暂时用字符串类型代替枚举，等schema完全稳定后再切换回枚举。但这种方式会丢失枚举的类型校验优势，业务层需要自己处理字符串的合法性校验，所以不太推荐长期使用。

总结 #

其实核心问题就是Pub/Sub的schema兼容性规则和原生Protobuf的默认规则有差异，只要调整兼容性模式，就可以正常使用枚举并进行新增值的操作，完全没必要放弃枚举的便利性。

内容来源于stack exchange