Protocol Buffers: Feldnummern, unbekannte Felder und die Regeln für die Weiterentwicklung einer Nachricht

Worum es geht

Eine .proto-Datei deklariert Nachrichten, deren Felder einen Typ, einen Namen und eine Feldnummer haben. Der Sprachleitfaden (zitiert) hält fest, dass die Nummer das Feld im Wire-Format identifiziert, innerhalb der Nachricht eindeutig sein muss, zwischen 1 und 536'870'911 liegt (19'000 bis 19'999 sind für die Implementierung reserviert) und nicht mehr geändert werden kann, sobald die Nachricht im Einsatz ist: eine Nummer zu "ändern" ist dasselbe wie das Feld zu löschen und ein neues hinzuzufügen. Die Nummern 1 bis 15 werden in einem Byte codiert, 16 bis 2047 in zwei, weshalb die am häufigsten gesetzten Felder die niedrigen Nummern erhalten sollten.

Warum es wichtig ist

Das Binärformat trägt nur Nummern und Wire-Types, nie Namen. Wird eine Nummer für ein anderes Feld wiederverwendet, kann ein Parser nicht erkennen, welche Definition die Daten geschrieben hat; der Leitfaden nennt Parsing-Fehler, durchgesickerte Daten und Korruption als Folgen, und die Best-Practices-Seite sagt es unverblümt: eine Tag-Nummer nie wiederverwenden. Die Weiterentwicklungsregeln sind das Einzige, was alte und neue Binaries miteinander sprechen lässt.

So wird es angewendet

• Das Hinzufügen von Feldern ist auf der Leitung unbedenklich: alter Code parst neue Nachrichten und behält die neuen Felder als unbekannte Felder (proto3 bewahrt sie und serialisiert sie erneut); neuer Code, der alte Nachrichten liest, sieht den Default-Wert – deshalb Defaults wählen, die "nicht gesetzt" bedeuten.
• Das Entfernen eines Feldes ist nur sicher, wenn seine Nummer in eine reserved-Anweisung aufgenommen wird, und bei Verwendung von JSON- oder Textformaten auch sein Name: reserved 2, 15, 9 to 11; und reserved "old_name";. Alternativ das Feld behalten und mit dem Präfix OBSOLETE_ umbenennen.
• Das Hinzufügen von Enum-Werten ist sicher; das Ändern der Nummer eines Feldes oder das Verschieben von Feldern in ein bestehendes oneof ist es nicht.
• int32, uint32, int64, uint64 und bool sind auf der Leitung kompatibel, aber verlustbehaftet: Ein Wert oberhalb des 32-Bit-Maximums, der als int32 gelesen wird, wird abgeschnitten. Einen Typ erst erweitern, wenn jeder Leser aktualisiert ist, und nie in einem Schema, das ausserhalb der eigenen Kontrolle veröffentlicht ist.
• Die Regeln mechanisch durchsetzen: Der Compiler weist die Verwendung reservierter Nummern zurück, und eine Registry oder ein Schema-Linter kann die übrigen unsicheren Änderungen ablehnen, bevor sie in einen Build gelangen.

Stolpersteine

Unbekannte Felder überstehen binäre Round-Trips, gehen aber verloren, wenn eine Nachricht in JSON umgewandelt oder Feld für Feld in eine neue Nachricht kopiert wird. Die obigen Regeln gelten für das Binärformat; ProtoJSON (zitiert) hat eine eigene Liste sicherer und unsicherer Änderungen, weil dort Feldnamen auf der Leitung erscheinen, und schreibt int64-Werte als Strings, damit kein Parser bei grossen Werten stillschweigend an Präzision verliert. Das Umnummerieren von Feldern, um die Datei aufzuräumen, ist eine vollständig inkompatible Änderung.