Protobuf 版本概述

Protobuf 版本功能概述。

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

版本不再是旧版本中固有的行为，而是表示一组功能，每个功能都有一个默认值（行为）。功能是文件、消息、字段、枚举等上的选项，用于指定 protoc、代码生成器和 protobuf 运行时的行为。当您的需求与您选择的版本默认行为不匹配时，您可以在这些不同级别（文件、消息、字段等）显式覆盖行为。您还可以覆盖您的覆盖。本主题后面词法作用域部分将对此进行更详细的介绍。

功能生命周期

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

版本 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";

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;
}

版本语法

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

message Player {
  // fields have explicit presence, so no explicit setting needed
  string name = 1;
  // 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;
}

Proto3 到版本

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

Proto3 语法

// 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 {
  // fields have explicit presence, so no explicit setting needed
  string name = 1;
  // 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;
}

词法作用域

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

以下代码示例显示了一些在文件、字段和枚举级别设置的功能。设置在高亮行中

edition = "2023";

option features.enum_type = CLOSED;

message Person {
  string name = 1;
  int32 id = 2 [features.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 迁移到版本时生成的代码会发生变化，但网络格式不会发生变化。您仍然可以使用版本语法 proto 定义访问 proto2 和 proto3 数据文件或文件流。