If an existing message type no longer meets all your needs – for example, you'd like the message format to have an extra field – but you'd still like to use code created with the old format, don't worry! It's very simple to update message types without breaking any of your existing code. Just remember the following rules:
如果一個(gè)已經(jīng)存在的message類型不再滿足你所有的需求 - 舉個(gè)例子,你想讓該消息類型擁有一個(gè)額外字段 - 但是你還想繼續(xù)使用舊格式創(chuàng)建出來的代碼,別擔(dān)心!更新消息類型是很簡(jiǎn)單的,且無需破壞任何現(xiàn)有代碼。只需記住以下這些規(guī)則:
Don't change the field numbers for any existing fields.
不要修改任何已存在字段的字段值。If you add new fields, any messages serialized by code using your "old" message format can still be parsed by your new generated code. You should keep in mind the default values for these elements so that new code can properly interact with messages generated by old code. Similarly, messages created by your new code can be parsed by your old code: old binaries simply ignore the new field when parsing. See the Unknown Fields section for details.
如果你添加新的字段,任何被使用“舊”消息格式的代碼序列化的消息,仍然可以被生成的代碼所解析。你應(yīng)該記住這些元素的默認(rèn)值,以便新代碼能夠正確的和舊代碼生成的message進(jìn)行交互。類似的,新代碼創(chuàng)建的message也可以被你的舊代碼所解析:解析時(shí)舊二進(jìn)制僅僅是忽略新字段。參閱[未知字段]((https://developers.google.com/protocol-buffers/docs/proto3#unknowns)章節(jié)獲取詳細(xì)信息。Fields can be removed, as long as the field number is not used again in your updated message type. You may want to rename the field instead, perhaps adding the prefix "OBSOLETE_", or make the field number reserved, so that future users of your
.protocan't accidentally reuse the number.
只要字段數(shù)字不會(huì)在你更新后的message類型中被再次使用,字段是可以被刪除的。你可能希望重命名該字段,或許添加"OBSOLETE_"前綴,或者將字段值標(biāo)記為保留,以便后來的.proto文件使用者不能一不小心重用這個(gè)數(shù)字。int32,uint32,int64,uint64, andboolare all compatible – this means you can change a field from one of these types to another without breaking forwards- or backwards-compatibility. If a number is parsed from the wire which doesn't fit in the corresponding type, you will get the same effect as if you had cast the number to that type in C++ (for example, if a 64-bit number is read as an int32, it will be truncated to 32 bits).
int32,uint32,int64,uint64, 和bool都是可兼容的 - 這意味著你可以從其中一種類型修改成其他類型,而不會(huì)破壞其向前或向后的兼容性。sint32andsint64are compatible with each other but are not compatible with the other integer types.
sint32和sint64是相互兼容的,但是不能和其他整型類型兼容。stringandbytesare compatible as long as the bytes are valid UTF-8.
只要是有效的UTF-8字節(jié)stringandbytes是兼容的。Embedded messages are compatible with
bytesif the bytes contain an encoded version of the message.
內(nèi)嵌message和bytes是兼容的,如果字節(jié)中包含了該message一個(gè)編碼后的版本。fixed32is compatible withsfixed32, andfixed64withsfixed64.
fixed32和sfixed32是兼容的,fixed64和sfixed64是兼容的。For
string,bytes, and message fields, singular fields are compatible withrepeatedfields. Given serialized data of a repeated field as input, clients that expect this field to be singular will take the last input value if it's a primitive type field or merge all input elements if it's a message type field. Note that this is not generally safe for numeric types, including bools and enums. Repeated fields of numeric types can be serialized in the packed format, which will not be parsed correctly when a singular field is expected.
對(duì)于string,bytes,和message字段,單一字段和repeated字段兼容。給定的重復(fù)字段的序列化后的數(shù)據(jù)作為輸入,而客戶端期望這個(gè)字段是單一數(shù)據(jù),那么如果這是一個(gè)原始類型字段則只取最后一條輸入值,或者如果這是一個(gè)message類型字段就合并所有輸入元素。注意這個(gè)對(duì)于數(shù)字類型并不是普遍安全的,包括布爾和枚舉。數(shù)字類型的重復(fù)字段可以被序列化為packed格式中,而當(dāng)需要單一字段時(shí)就不會(huì)正確解析。enumis compatible withint32,uint32,int64, anduint64in terms of wire format (note that values will be truncated if they don't fit). However be aware that client code may treat them differently when the message is deserialized: for example, unrecognized proto3enumtypes will be preserved in the message, but how this is represented when the message is deserialized is language-dependent. Int fields always just preserve their value.
在線路格式方面enum與int32,uint32、int64及uint64兼容(如果他們不合適數(shù)據(jù)將會(huì)被截?cái)啵?。然而要知道?dāng)message被序列化時(shí)客戶端狀態(tài)碼必須區(qū)別對(duì)待它們:舉個(gè)例子,未識(shí)別的proto3enum類型會(huì)被保留在message中,但是message反序列化時(shí)如何保存取決于語言。對(duì)于整型字段總是只保存它們的值。Changing a single
optionalfield or extension into a member of a newoneofis safe and binary compatible. Moving multiple fields into a newoneofmay be safe if you are sure that no code sets more than one at a time. Moving any fields into an existingoneofis not safe. Likewise, changing a single fieldoneofto anoptionalfield or extension is safe.
修改一個(gè)單一optional字段或者擴(kuò)展為oneof新的一員是安全的,且和binary兼容。如果你能保證沒有代碼一次設(shè)置超過一個(gè),將多個(gè)字段修改為新的oneof可能是安全的。將任何字段修改為一個(gè)已經(jīng)存在的oneof是不安全的。同樣地,修改一個(gè)單一字段oneof為optional字段或者擴(kuò)展是安全。