proto3:Updating A Message Type - 更新message類型

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 .proto can't accidentally reuse the number.
    只要字段數(shù)字不會(huì)在你更新后的message類型中被再次使用,字段是可以被刪除的。你可能希望重命名該字段,或許添加"OBSOLETE_"前綴,或者將字段值標(biāo)記為保留,以便后來的.proto文件使用者不能一不小心重用這個(gè)數(shù)字。

  • int32, uint32, int64, uint64, and bool are 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ì)破壞其向前或向后的兼容性。

  • sint32 and sint64 are compatible with each other but are not compatible with the other integer types.
    sint32sint64是相互兼容的,但是不能和其他整型類型兼容。

  • string and bytes are compatible as long as the bytes are valid UTF-8.
    只要是有效的UTF-8字節(jié)string and bytes是兼容的。

  • Embedded messages are compatible with bytes if the bytes contain an encoded version of the message.
    內(nèi)嵌message和bytes是兼容的,如果字節(jié)中包含了該message一個(gè)編碼后的版本。

  • fixed32 is compatible with sfixed32, and fixed64 with sfixed64.
    fixed32sfixed32是兼容的,fixed64sfixed64是兼容的。

  • For string, bytes, and message fields, singular fields are compatible with repeated fields. 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ì)正確解析。

  • enum is compatible with int32, uint32, int64, and uint64 in 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 proto3 enum types 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.
    在線路格式方面enumint32, uint32、int64uint64兼容(如果他們不合適數(shù)據(jù)將會(huì)被截?cái)啵?。然而要知道?dāng)message被序列化時(shí)客戶端狀態(tài)碼必須區(qū)別對(duì)待它們:舉個(gè)例子,未識(shí)別的proto3 enum類型會(huì)被保留在message中,但是message反序列化時(shí)如何保存取決于語言。對(duì)于整型字段總是只保存它們的值。

  • Changing a single optional field or extension into a member of a new oneof is safe and binary compatible. Moving multiple fields into a new oneof may be safe if you are sure that no code sets more than one at a time. Moving any fields into an existing oneof is not safe. Likewise, changing a single field oneof to an optional field or extension is safe.
    修改一個(gè)單一optional字段或者擴(kuò)展為oneof的一員是安全的,且和binary兼容。如果你能保證沒有代碼一次設(shè)置超過一個(gè),將多個(gè)字段修改為新的oneof可能是安全的。將任何字段修改為一個(gè)已經(jīng)存在的oneof是不安全的。同樣地,修改一個(gè)單一字段oneofoptional字段或者擴(kuò)展是安全。

?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成,瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明:文章內(nèi)容(如有圖片或視頻亦包括在內(nèi))由作者上傳并發(fā)布,文章內(nèi)容僅代表作者本人觀點(diǎn),簡(jiǎn)書系信息發(fā)布平臺(tái),僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容