Protobuf 版本概述

Protobuf 版本功能的概述。

Protobuf 版本取代了我们为 Protocol Buffers 使用的 proto2 和 proto3 指定。您无需在 proto 定义文件的顶部添加 syntax = "proto2" 或 syntax = "proto3"，而是使用版本号（例如 edition = "2023"）来指定文件将具有的默认行为。版本使语言能够随着时间的推移逐步发展。

版本并非像旧版本那样具有硬编码行为，而是表示特性的集合，每个特性都有一个默认值（行为）。特性是文件、消息、字段、枚举等上的选项，用于指定 protoc、代码生成器和 protobuf 运行时的行为。当您的需求与您选择的版本默认行为不匹配时，您可以显式覆盖这些不同级别（文件、消息、字段等）的行为。您还可以覆盖您的覆盖。本主题稍后关于词法作用域的部分将更详细地介绍这一点。

最新发布的版本是 2023。

特性的生命周期

版本为特性的生命周期提供了基本增量。特性具有预期的生命周期：引入它、更改其默认行为、弃用它，然后删除它。例如

版本 2031 创建了 feature.amazing_new_feature，默认值为 false。此值保持与所有早期版本相同的行为。也就是说，它默认为无影响。
开发者将其 .proto 文件更新为 edition = "2031"。
稍后的版本（例如版本 2033）将 feature.amazing_new_feature 的默认值从 false 切换为 true。这是所有 proto 的期望行为，也是 protobuf 团队创建此特性的原因。
使用 Prototiller 工具将早期版本的 proto 文件迁移到版本 2033 会根据需要添加显式的 feature.amazing_new_feature = false 条目，以继续保留以前的行为。当开发者希望新行为应用于其 .proto 文件时，他们会删除这些新添加的设置。

在某个时候，feature.amazing_new_feature 在某个版本中被标记为已弃用，并在稍后的版本中被删除。
当特性被删除时，该行为的代码生成器和支持它的运行时库也可能被删除。但是，时间线将是宽松的。按照生命周期早期步骤中的示例，弃用可能会在版本 2034 中发生，但直到大约两年后的版本 2036 才会被删除。删除特性将始终启动主版本号的提升。

由于这种生命周期，任何不使用已弃用特性的 .proto 文件都可以从一个版本无操作升级到下一个版本。您将有完整的 Google 迁移窗口加上弃用窗口来升级您的代码。

前面的生命周期示例对特性使用了布尔值，但特性也可以使用枚举。例如，features.field_presence 具有值 LEGACY_REQUIRED、EXPLICIT 和 IMPLICIT。

迁移到 Protobuf 版本

版本不会破坏现有二进制文件，也不会更改消息的二进制、文本或 JSON 序列化格式。第一个版本尽可能做到最小程度的破坏性。第一个版本建立了基线，并将 proto2 和 proto3 定义合并为新的单一定义格式。

当后续版本发布时，特性的默认行为可能会更改。您可以让 Prototiller 对您的 .proto 文件进行无操作转换，或者您可以选择接受部分或全部新行为。版本计划大约每年发布一次。

Proto2 到版本

本节显示了一个 proto2 文件，以及在运行 Prototiller 工具将定义文件更改为使用 Protobuf 版本语法后的样子。

Proto2 语法

// proto2 file
syntax = "proto2";

package com.example;

message Player {
  // in proto2, optional fields have explicit presence
  optional string name = 1 [default = "N/A"];
  // 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;

  reserved "gender";
}

版本语法

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

package com.example;

option features.utf8_validation = NONE;

message Player {
  // fields have explicit presence, so no explicit setting needed
  string name = 1 [default = "N/A"];
  // to match the proto2 behavior, LEGACY_REQUIRED is set at the field level
  int32 id = 2 [features.field_presence = LEGACY_REQUIRED];
  // to match the proto2 behavior, EXPANDED is set at the field level
  repeated int32 scores = 3 [features.repeated_field_encoding = EXPANDED];

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

  Handed handed = 4;

  reserved gender;
}

Proto3 到版本

本节显示了一个 proto3 文件，以及在运行 Prototiller 工具将定义文件更改为使用 Protobuf 版本语法后的样子。

Proto3 语法

// proto3 file
syntax = "proto3";

package com.example;

message Player {
  // in proto3, optional fields have explicit presence
  optional string name = 1 [default = "N/A"];
  // 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;

  reserved "gender";
}

版本语法

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

package com.example;

message Player {
  // fields have explicit presence, so no explicit setting needed
  string name = 1 [default = "N/A"];
  // to match the proto3 behavior, IMPLICIT is set at the field level
  int32 id = 2 [features.field_presence = IMPLICIT];
  // PACKED is the default state, and is provided just for illustration
  repeated int32 scores = 3 [features.repeated_field_encoding = PACKED];

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

  Handed handed = 4;

  reserved gender;
}

词法作用域

版本语法支持词法作用域，并具有每个特性允许的目标列表。例如，在第一个版本中，特性只能在文件级别或最低粒度级别指定。词法作用域的实现使您能够为整个文件中的特性设置默认行为，然后在消息、字段、枚举、枚举值、oneof、服务或方法级别覆盖该行为。在较高级别（文件、消息）进行的设置在同一作用域（字段、枚举值）内未进行设置时适用。任何未显式设置的特性都符合 .proto 文件使用的版本中定义的行为。

以下代码示例显示了一些在文件、字段和枚举级别设置的特性。

edition = "2023";

option features.enum_type = CLOSED;

message Person {
  string name = 1;
  int32 id = 2 [features.field_presence = IMPLICIT];

  enum Pay_Type {
    PAY_TYPE_UNSPECIFIED = 1;
    PAY_TYPE_SALARY = 2;
    PAY_TYPE_HOURLY = 3;
  }

  enum Employment {
    option features.enum_type = OPEN;
    EMPLOYMENT_UNSPECIFIED = 0;
    EMPLOYMENT_FULLTIME = 1;
    EMPLOYMENT_PARTTIME = 2;
  }
  Employment employment = 4;
}

在前面的示例中，presence 特性设置为 IMPLICIT；如果未设置，则默认为 EXPLICIT。Pay_Type enum 将为 CLOSED，因为它应用了文件级设置。但是，Employment enum 将为 OPEN，因为它是在枚举中设置的。

Prototiller

当 Prototiller 工具启动时，我们将提供迁移指南和迁移工具，以简化版本之间以及版本内的迁移。该工具将使您能够

大规模地将 proto2 和 proto3 定义文件转换为新的版本语法
将文件从一个版本迁移到另一个版本
以其他方式操作 proto 文件

向后兼容性

我们正在构建 Protobuf 版本，使其尽可能做到最小程度的破坏性。例如，您可以将 proto2 和 proto3 定义导入到基于版本的定义文件中，反之亦然

// file myproject/foo.proto
syntax = "proto2";

enum Employment {
  EMPLOYMENT_UNSPECIFIED = 0;
  EMPLOYMENT_FULLTIME = 1;
  EMPLOYMENT_PARTTIME = 2;
}

// file myproject/edition.proto
edition = "2023";

import "myproject/foo.proto";

虽然当您从 proto2 或 proto3 迁移到版本时，生成的代码会发生更改，但 wire 格式不会更改。您仍然可以使用您的版本语法 proto 定义访问 proto2 和 proto3 数据文件或文件流。

语法更改

与 proto2 和 proto3 相比，版本在语法上有一些更改。

语法描述。 您使用 edition 元素而不是 syntax 元素

syntax = "proto2";
syntax = "proto3";
edition = "2028";

保留名称。 在保留字段名称和枚举值名称时，您不再需要将它们放在引号中

reserved foo, bar;

Group 语法。 proto2 中可用的 Group 语法在版本中被删除。组使用的特殊 wire 格式仍然可以通过使用 DELIMITED 消息编码来使用。

Required 标签。 仅在 proto2 中可用的 required 标签在版本中不可用。底层功能仍然可以通过使用 features.field_presence=LEGACY_REQUIRED 来使用。