Proto2服务端新增消息类型未同步客户端时编解码异常问题咨询

解码异常原因 #

首先你贴出的服务端proto代码中Wrapper消息定义缺少闭合的}，如果实际代码存在该语法错误，protoc编译时会出现字段映射异常，进而导致解码结果错乱。如果这个错误是你贴代码时疏漏的，可排查以下两个核心原因：

1. 新旧编译产物冲突：服务端更新proto定义后没有彻底删除旧的*_pb2.py编译文件，新旧代码的字段映射关系混杂，运行时加载了错误的解析规则，导致oneof字段匹配偏移。
2. runtime版本兼容bug：部分3.20版本以下的protobuf Python runtime存在oneof字段解析的已知缺陷，当oneof内新增字段后，旧版本客户端编码的消息在新版本服务端解码时，会出现字段号匹配错误的问题，你遇到的login_event被识别为logoff_event就是典型的匹配偏移现象。

提升兼容性的最佳实践 #

• 严格遵守字段号不可变规则：已投入使用的字段永远不要修改字段号、字段类型，也不要复用已废弃的字段号，废弃字段统一用reserved关键字标注，避免后续扩展时误用到旧字段号。
• 每次修改proto后先做语法校验：使用protoc --check-syntax 你的proto文件路径命令校验语法正确性，避免出现括号缺失、关键字拼写错误等低级问题。
• 彻底清理编译产物再重新生成：更新proto定义后，先删除所有旧的编译生成文件，再执行protoc编译命令，避免新旧代码冲突。
• 统一客户端与服务端的protobuf runtime版本：尽量保持两端的大版本号一致，推荐统一使用3.20及以上的稳定版本，规避已知的解析bug。
• oneof扩展规则：oneof内新增字段时禁止修改已有字段的编号，不要在oneof外定义和oneof内字段号重复的字段。
• 所有新增字段使用optional类型：禁止使用required类型定义新增字段，required字段会严重破坏前后向兼容性。
• 提前预留扩展字段号：定义消息尤其是oneof类型字段时，提前预留一部分字段号用于后续扩展，避免后续新增字段时不需要调整已有字段的编号。
• 解码增加合法性校验：解码完成后增加必要的业务合法性校验，比如oneof字段的取值范围校验，避免错误解码的消息流入业务逻辑。
• MQTT场景额外注意：保证MQTT传输的protobuf payload要完整，不要截短、拼接多余字节，protobuf解码依赖完整的二进制流，流数据异常会直接导致解码偏移。

内容的提问来源于stack exchange，提问作者king-network