Language Guide (proto3) | proto3 语言指南(七)更新消息类型
Updating A Message Type - 更新消息类型
如果现有的消息类型不再满足您的所有需要(例如,您希望消息格式有一个额外的字段),但是您仍然希望使用用旧格式创建的代码,不要担心!在不破坏任何现有代码的情况下更新消息类型非常简单。记住以下规则:
- 不要更改任何现有字段的字段编号。
- 如果添加新字段,则使用“旧”消息格式的代码序列化的任何消息仍然可以由新生成的代码进行解析。您应该记住这些元素的默认值,以便新代码可以正确地与旧代码生成的消息交互。类似地,由新代码创建的消息也可以由旧代码解析:旧二进制文件在解析时忽略新字段。有关详细信息,请参阅未知字段部分。
- 可以删除字段,前提是在更新的消息类型中不再使用此字段编号。您可能需要重命名字段,或者添加前缀
OBSOLETE_
,或者使用reserved
保留字段编号,以便.proto
的未来用户不会意外地重用该编号。 int32
、uint32
、int64
、uint64
和bool
都是兼容的——这意味着您可以将字段从一种类型更改为另一种类型,而不会破坏向前或向后的兼容性。如果从不适合于相应类型的Wire
中解析一个数,则将获得与在C++中将该数转换为该类型的相同效果(例如,如果64位数字被读取为一个int32
类型,则它将被截断到32位)。sint32
和sint64
彼此兼容,但与其他整数类型不兼容。- 只要字节是有效的
UTF-8
编码,string
和bytes
就可以兼容。 - 如果
bytes
包含消息的编码版本,则嵌入的消息与字节兼容。 fixed32
与sfixed32
兼容,fixed64
与sfixed64
兼容。- 对于
string
、bytes
和消息字段,optional
与repeated
兼容。给定重复字段的序列化数据作为输入,如果该字段是基元类型字段,则期望该字段为optional
(可选的)字段的客户端将获取最后一个输入值;如果该字段是消息类型字段,则合并所有输入元素。请注意,对于数值类型(包括bool
和enum
),这通常是不安全的。数字类型的重复字段可以按压缩格式序列化,当需要可选字段时,将无法正确解析压缩格式。 enum
在wire格式化
方面与int32
、uint32
、int64
和uint64
兼容(请注意,如果值不适合,它们将被截断)。但是,请注意,在反序列化消息时,客户端代码可能会对它们进行不同的处理:例如,未识别的proto3
枚举类型将保留在消息中,但在反序列化消息时如何表示这些类型取决于客户端语言。整型字段总是保持它们的值。- 将单个值更改为新
oneof
值的成员是安全的,并且二进制兼容。如果您确定没有代码一次设置多个字段,那么将多个字段移到其中一个新oneof
字段中可能是安全的。将任何字段移到现有oneof
字段中都不安全。