Änderungen angekündigt am 29. Juni 2023

Kurz gesagt: Wir planen, Protobuf Editions im zweiten Halbjahr 2023 für das Open-Source-Projekt freizugeben. Obwohl es bei der ersten Veröffentlichung keine Verpflichtung gibt, von der proto2/proto3-Syntax zur Editions-Syntax zu wechseln, empfehlen wir Ihnen, einen Wechsel in der zukünftigen Zeitplanung Ihres Softwareprojekts zu planen.

Protobuf-Editionen

Protobuf Editions ersetzen die Bezeichnungen proto2 und proto3, die wir für Protocol Buffers verwendet haben. Anstatt syntax = "proto2" oder syntax = "proto3" am Anfang von proto-Definitionsdateien hinzuzufügen, verwenden Sie eine Editionsnummer, z. B. edition = "2024", um die Standardverhalten Ihrer Datei festzulegen. Editions ermöglichen es der Sprache, sich im Laufe der Zeit inkrementell weiterzuentwickeln.

Anstatt der hartkodierten Verhaltensweisen in älteren Versionen stellen Editions eine Sammlung von „Features“ mit einem Standardwert (Verhalten) pro Feature dar, den Sie überschreiben können. Features sind Optionen für eine Datei, Nachricht, ein Feld, eine Aufzählung usw., die das Verhalten von protoc, den Codegeneratoren und den protobuf-Laufzeitumgebungen festlegen. Sie können das gewünschte Verhalten auf diesen verschiedenen Ebenen (Datei, Nachricht, Feld, ...) explizit überschreiben, wenn Ihre Anforderungen nicht mit dem Standardverhalten für die von Ihnen ausgewählte Edition übereinstimmen.

Editions brechen keine bestehenden Binärdateien und die erste Edition wird minimal störend sein; sie wird die Basislinie festlegen und proto2- und proto3-Definitionen zu einem neuen, einheitlichen Definitionsformat zusammenführen. Es sind keine Änderungen an Ihrem Code erforderlich. Wir werden ein Tool namens Prototiller bereitstellen, um .proto-Dateien zu migrieren. Die folgenden Beispiele zeigen eine proto2-Definitionsdatei und eine proto3-Datei und wie jede nach der Verwendung von Prototiller zur Konvertierung in das Protobuf Editions-Format aussehen könnte.

// proto2 file
syntax = "proto2";

message Player {
  // in proto2, optional fields have explicit presence
  optional string name = 1;
  // proto2 still supports the problematic "required" field rule
  required int32 id = 2;
  // in proto2 this is not packed by default
  repeated int32 scores = 3;

  enum Handed {
    HANDED_UNSPECIFIED = 0,
    HANDED_LEFT = 1,
    HANDED_RIGHT = 2,
    HANDED_AMBIDEXTROUS = 3,
  }

  // in proto2 enums are closed
  optional Handed handed = 4;
}

// Editions version of proto2 file
edition = "2023";

message Player {
  string name = 1;
  int32 id = 2 [features.field_presence = LEGACY_REQUIRED];
  repeated int32 scores = 3 [features.repeated_field_encoding = EXPANDED];

  enum Handed {
    // this overrides the default Edition 2023 behavior, which is OPEN
    option features.enum = CLOSED;
    HANDED_UNSPECIFIED = 0,
    HANDED_LEFT = 1,
    HANDED_RIGHT = 2,
    HANDED_AMBIDEXTROUS = 3,
  }

  Handed handed = 4;
}

Und so könnte eine ähnliche proto3-Definitionsdatei aussehen

// proto3 file
syntax = "proto3";

message Player {
  // in proto3, optional fields have explicit presence
  optional string name = 1;
  // in proto3 no specified field rule defaults to implicit presence
  int32 id = 2;
  // in proto3 this is packed by default
  repeated int32 scores = 3;

  enum Handed {
    HANDED_UNSPECIFIED = 0,
    HANDED_LEFT = 1,
    HANDED_RIGHT = 2,
    HANDED_AMBIDEXTROUS = 3,
  }

  // in proto3 enums are open
  optional Handed handed = 4;
}

// Editions version of proto3 file
edition = "2023";

message Player {
  string name = 1;
  int32 id = 2 [features.field_presence = IMPLICIT];
  repeated int32 scores = 3;

  enum Handed {
    HANDED_UNSPECIFIED = 0,
    HANDED_LEFT = 1,
    HANDED_RIGHT = 2,
    HANDED_AMBIDEXTROUS = 3,
  }

  Handed handed = 4;
}

Während die in diesem Thema bereitgestellten Beispiele eine direkte Übersetzung von proto2 und proto3 in die entsprechende Darstellung mit Protobuf Editions zeigen, können Sie die Einstellungen an die Bedürfnisse Ihres Projekts anpassen.

Features haben einen Lebenszyklus, der von den Veröffentlichungen von Editions gesteuert wird. Zum Beispiel könnte features.awesome_new_feature in Edition 2031 hinzugefügt werden, wobei das neue Verhalten für alle Definitionen gilt, die das neue Verhalten nicht explizit überschreiben. In Edition 2033 wird das neue Feature als veraltet markiert. Überschreibungen funktionieren weiterhin, aber Entwickler werden darauf aufmerksam gemacht, dass sie sich bald an das neue Verhalten anpassen müssen. In Edition 2036 wird das Feature entfernt und das neue Verhalten gilt für alle protos; es gibt zu diesem Zeitpunkt keine Möglichkeit mehr, das neue Verhalten zu überschreiben.

Abbildung 1: Flussdiagramm des Editions-Lebenszyklus

Editions werden voraussichtlich etwa einmal im Jahr veröffentlicht. Weitere Informationen zu Protobuf Editions finden Sie in der Übersicht unter https://protobuf.de/editions/overview.