C++ 生成代码指南

描述了协议缓冲区编译器为任何给定的协议定义生成的 C++ 代码。

proto2 和 proto3 生成代码之间的任何差异都会突出显示 - 请注意，这些差异在于本文档中描述的生成代码，而不是基本消息类/接口，它们在两个版本中是相同的。在阅读本文档之前，您应该阅读 proto2 语言指南 和/或 proto3 语言指南。

编译器调用

当使用 --cpp_out= 命令行标志调用协议缓冲区编译器时，它会生成 C++ 输出。 --cpp_out= 选项的参数是您希望编译器写入 C++ 输出的目录。编译器为每个 .proto 文件输入创建一个头文件和一个实现文件。输出文件的名称是通过获取 .proto 文件的名称并进行两项更改来计算的

  • 扩展名 (.proto) 将分别替换为头文件或实现文件的 .pb.h 或 .pb.cc。
  • proto 路径（使用 --proto_path= 或 -I 命令行标志指定）将替换为输出路径（使用 --cpp_out= 标志指定）。

因此，例如，假设您按如下方式调用编译器

protoc --proto_path=src --cpp_out=build/gen src/foo.proto src/bar/baz.proto

编译器将读取文件 src/foo.proto 和 src/bar/baz.proto 并生成四个输出文件：build/gen/foo.pb.h、build/gen/foo.pb.cc、build/gen/bar/baz.pb.h、build/gen/bar/baz.pb.cc。编译器将自动创建目录 build/gen/bar（如果需要），但它不会创建 build 或 build/gen；它们必须已经存在。

包

如果 .proto 文件包含 package 声明，则文件的全部内容将放置在相应的 C++ 命名空间中。例如，给定 package 声明

package foo.bar;

文件中的所有声明都将驻留在 foo::bar 命名空间中。

消息

给定一个简单的消息声明

message Foo {}

协议缓冲区编译器生成一个名为 Foo 的类，该类公开派生自 google::protobuf::Message。该类是一个具体类；没有未实现的纯虚方法。 Message 中是虚方法但不是纯虚方法的方法可能会或可能不会被 Foo 覆盖，具体取决于优化模式。默认情况下，Foo 实现所有方法的专门版本以获得最大速度。但是，如果 .proto 文件包含以下行

option optimize_for = CODE_SIZE;

那么 Foo 将仅覆盖运行所需的最小方法集，并依赖于其余方法的基于反射的实现。这显着减小了生成代码的大小，但也降低了性能。或者，如果 .proto 文件包含

option optimize_for = LITE_RUNTIME;

那么 Foo 将包含所有方法的快速实现，但将实现 google::protobuf::MessageLite 接口，该接口仅包含 Message 方法的子集。特别是，它不支持描述符或反射。但是，在这种模式下，生成的代码只需要链接到 libprotobuf-lite.so（Windows 上为 libprotobuf-lite.lib），而不是 libprotobuf.so（libprotobuf.lib）。“lite”库比完整库小得多，更适合资源受限的系统，例如移动电话。

您不应创建自己的 Foo 子类。如果您对该类进行子类化并覆盖虚方法，则覆盖可能会被忽略，因为许多生成的方法调用都进行了去虚化以提高性能。

Message 接口定义了允许您检查、操作、读取或写入整个消息的方法，包括从二进制字符串解析和序列化为二进制字符串。

  • bool ParseFromString(::absl::string_view data)：从给定的序列化二进制字符串（也称为线路格式）解析消息。
  • bool SerializeToString(string* output) const：将给定消息序列化为二进制字符串。
  • string DebugString()：返回一个字符串，给出 proto 的 text_format 表示形式（仅应用于调试）。

除了这些方法之外，Foo 类还定义了以下方法

  • Foo()：默认构造函数。
  • ~Foo()：默认析构函数。
  • Foo(const Foo& other)：复制构造函数。
  • Foo(Foo&& other)：移动构造函数。
  • Foo& operator=(const Foo& other)：赋值运算符。
  • Foo& operator=(Foo&& other)：移动赋值运算符。
  • void Swap(Foo* other)：与另一个消息交换内容。
  • const UnknownFieldSet& unknown_fields() const：返回解析此消息时遇到的未知字段集。如果在 .proto 文件中指定了 option optimize_for = LITE_RUNTIME，则返回类型将更改为 std::string&。
  • UnknownFieldSet* mutable_unknown_fields()：返回指向解析此消息时遇到的可变未知字段集的指针。如果在 .proto 文件中指定了 option optimize_for = LITE_RUNTIME，则返回类型将更改为 std::string*。

该类还定义了以下静态方法

  • static const Descriptor* descriptor()：返回类型的描述符。其中包含有关类型的信息，包括它具有哪些字段以及它们的类型是什么。这可以与 反射 一起使用，以编程方式检查字段。
  • static const Foo& default_instance()：返回 Foo 的 const 单例实例，该实例与新构造的 Foo 实例相同（因此所有奇异字段都未设置，所有重复字段都为空）。请注意，消息的默认实例可以用作工厂，通过调用其 New() 方法。

生成的文件名

保留关键字 在生成的输出中附加下划线。

例如，以下 proto3 定义语法

message MyMessage {
  string false = 1;
  string myFalse = 2;
}

生成以下部分输出

  void clear_false_() ;
  const std::string& false_() const;
  void set_false_(Arg_&& arg, Args_... args);
  std::string* mutable_false_();
  PROTOBUF_NODISCARD std::string* release_false_();
  void set_allocated_false_(std::string* ptr);

  void clear_myfalse() ;
  const std::string& myfalse() const;
  void set_myfalse(Arg_&& arg, Args_... args);
  std::string* mutable_myfalse();
  PROTOBUF_NODISCARD std::string* release_myfalse();
  void set_allocated_myfalse(std::string* ptr);

嵌套类型

消息可以在另一个消息内部声明。例如

message Foo {
  message Bar {}
}

在这种情况下，编译器生成两个类：Foo 和 Foo_Bar。此外，编译器在 Foo 内部生成一个 typedef，如下所示

typedef Foo_Bar Bar;

这意味着您可以像使用嵌套类 Foo::Bar 一样使用嵌套类型的类。但是，请注意，C++ 不允许前向声明嵌套类型。如果您想在前向声明另一个文件中的 Bar 并使用该声明，则必须将其标识为 Foo_Bar。

字段

除了上一节中描述的方法之外，协议缓冲区编译器还为 .proto 文件中消息内定义的每个字段生成一组访问器方法。这些方法采用小写/蛇形命名法，例如 has_foo() 和 clear_foo()。

除了访问器方法之外，编译器还为每个字段生成一个整数常量，其中包含其字段编号。常量名称是字母 k，后跟转换为驼峰式命名的字段名称，后跟 FieldNumber。例如，给定字段 optional int32 foo_bar = 5;，编译器将生成常量 static const int kFooBarFieldNumber = 5;。

对于返回 const 引用的字段访问器，当对消息进行下一次修改访问时，该引用可能会失效。这包括调用任何字段的任何非 const 访问器、调用从 Message 继承的任何非 const 方法或通过其他方式修改消息（例如，通过使用消息作为 Swap() 的参数）。相应地，仅当在此期间未对消息进行修改访问时，返回引用的地址才能保证在访问器的不同调用中保持相同。

对于返回指针的字段访问器，当对消息进行下一次修改或非修改访问时，该指针可能会失效。这包括，无论是否为常量，调用任何字段的任何访问器、调用从 Message 继承的任何方法或通过其他方式访问消息（例如，通过使用复制构造函数复制消息）。相应地，永远不能保证返回指针的值在访问器的两个不同调用中保持相同。

可选数值字段（proto2 和 proto3）

对于以下任一字段定义

optional int32 foo = 1;
required int32 foo = 1;

编译器将生成以下访问器方法

  • bool has_foo() const：如果字段已设置，则返回 true。
  • int32 foo() const：返回字段的当前值。如果字段未设置，则返回默认值。
  • void set_foo(int32 value)：设置字段的值。调用此方法后，has_foo() 将返回 true，foo() 将返回 value。
  • void clear_foo()：清除字段的值。调用此方法后，has_foo() 将返回 false，foo() 将返回默认值。

对于其他数值字段类型（包括 bool），int32 将根据 标量值类型表 替换为相应的 C++ 类型。

隐式存在数值字段（proto3）

对于以下字段定义

int32 foo = 1;  // no field label specified, defaults to implicit presence.

编译器将生成以下访问器方法

  • int32 foo() const：返回字段的当前值。如果字段未设置，则返回 0。
  • void set_foo(int32 value)：设置字段的值。调用此方法后，foo() 将返回 value。
  • void clear_foo()：清除字段的值。调用此方法后，foo() 将返回 0。

对于其他数值字段类型（包括 bool），int32 将根据 标量值类型表 替换为相应的 C++ 类型。

可选字符串/字节字段（proto2 和 proto3）

注意： 从 2023 版本开始，如果 features.(pb.cpp).string_type 设置为 VIEW，则将生成 string_view API。

对于以下任何字段定义

optional string foo = 1;
required string foo = 1;
optional bytes foo = 1;
required bytes foo = 1;

编译器将生成以下访问器方法

  • bool has_foo() const：如果字段已设置，则返回 true。
  • const string& foo() const：返回字段的当前值。如果字段未设置，则返回默认值。
  • void set_foo(::absl::string_view value)：设置字段的值。调用此方法后，has_foo() 将返回 true，foo() 将返回 value 的副本。
  • void set_foo(const string& value)：设置字段的值。调用此方法后，has_foo() 将返回 true，foo() 将返回 value 的副本。
  • void set_foo(string&& value)：设置字段的值，从传递的字符串移动。调用此方法后，has_foo() 将返回 true，foo() 将返回 value 的副本。
  • void set_foo(const char* value)：使用 C 风格的空终止字符串设置字段的值。调用此方法后，has_foo() 将返回 true，foo() 将返回 value 的副本。
  • void set_foo(const char* value, int size)：使用显式指定大小的字符串（而不是通过查找空终止符字节确定）设置字段的值。调用此方法后，has_foo() 将返回 true，foo() 将返回 value 的副本。
  • string* mutable_foo()：返回指向存储字段值的可变 string 对象的指针。如果在调用之前字段未设置，则返回的字符串将为空（不是默认值）。调用此方法后，has_foo() 将返回 true，foo() 将返回写入给定字符串的任何值。
  • void clear_foo()：清除字段的值。调用此方法后，has_foo() 将返回 false，foo() 将返回默认值。
  • void set_allocated_foo(string* value)：将 string 对象设置为字段，并释放以前的字段值（如果存在）。如果 string 指针不是 NULL，则消息将获得已分配的 string 对象的所有权，并且 has_foo() 将返回 true。消息可以随时删除已分配的 string 对象，因此对该对象的引用可能会失效。否则，如果 value 为 NULL，则行为与调用 clear_foo() 相同。
  • string* release_foo()：释放字段的所有权并返回 string 对象的指针。调用此方法后，调用者将获得已分配的 string 对象的所有权，has_foo() 将返回 false，foo() 将返回默认值。

隐式存在字符串/字节字段（proto3）

注意： 从 2023 版本开始，如果 features.(pb.cpp).string_type 设置为 VIEW，则将生成 string_view API。

对于以下任一字段定义

string foo = 1;  // no field label specified, defaults to implicit presence.
bytes foo = 1;

编译器将生成以下访问器方法

  • const string& foo() const：返回字段的当前值。如果字段未设置，则返回空字符串/空字节。
  • void set_foo(::absl::string_view value)：设置字段的值。调用此方法后，foo() 将返回 value 的副本。
  • void set_foo(const string& value)：设置字段的值。调用此方法后，foo() 将返回 value 的副本。
  • void set_foo(string&& value)：设置字段的值，从传递的字符串移动。调用此方法后，foo() 将返回 value 的副本。
  • void set_foo(const char* value)：使用 C 风格的空终止字符串设置字段的值。调用此方法后，foo() 将返回 value 的副本。
  • void set_foo(const char* value, int size)：使用显式指定大小的字符串（而不是通过查找空终止符字节确定）设置字段的值。调用此方法后，foo() 将返回 value 的副本。
  • string* mutable_foo()：返回指向存储字段值的可变 string 对象的指针。如果在调用之前字段未设置，则返回的字符串将为空。调用此方法后，foo() 将返回写入给定字符串的任何值。
  • void clear_foo()：清除字段的值。调用此方法后，foo() 将返回空字符串/空字节。
  • void set_allocated_foo(string* value)：将 string 对象设置为字段，并释放以前的字段值（如果存在）。如果 string 指针不是 NULL，则消息将获得已分配的 string 对象的所有权。消息可以随时删除已分配的 string 对象，因此对该对象的引用可能会失效。否则，如果 value 为 NULL，则行为与调用 clear_foo() 相同。
  • string* release_foo()：释放字段的所有权并返回 string 对象的指针。调用此方法后，调用者将获得已分配的 string 对象的所有权，foo() 将返回空字符串/空字节。

支持 Cord 的奇异字节字段

v23.0 为奇异 bytes 字段（包括 oneof 字段）添加了对 absl::Cord 的支持。奇异 string、repeated string 和 repeated bytes 字段不支持使用 Cord。

要设置奇异 bytes 字段以使用 absl::Cord 存储数据，请使用以下语法

optional bytes foo = 25 [ctype=CORD];
bytes bar = 26 [ctype=CORD];

cord 不适用于 repeated bytes 字段。 Protoc 忽略这些字段上的 [ctype=CORD] 设置。

编译器将生成以下访问器方法

  • const ::absl::Cord& foo() const：返回字段的当前值。如果字段未设置，则返回空的 Cord（proto3）或默认值（proto2）。
  • void set_foo(const ::absl::Cord& value)：设置字段的值。调用此方法后，foo() 将返回 value。
  • void set_foo(::absl::string_view value)：设置字段的值。调用此方法后，foo() 将以 absl::Cord 形式返回 value。
  • void clear_foo()：清除字段的值。调用此方法后，foo() 将返回空的 Cord（proto3）或默认值（proto2）。
  • bool has_foo()：如果字段已设置，则返回 true。

可选枚举字段（proto2 和 proto3）

给定枚举类型

enum Bar {
  BAR_UNSPECIFIED = 0;
  BAR_VALUE = 1;
  BAR_OTHER_VALUE = 2;
}

对于以下任一字段定义

optional Bar bar = 1;
required Bar bar = 1;

编译器将生成以下访问器方法

  • bool has_bar() const：如果字段已设置，则返回 true。
  • Bar bar() const：返回字段的当前值。如果字段未设置，则返回默认值。
  • void set_bar(Bar value)：设置字段的值。调用此方法后，has_bar() 将返回 true，bar() 将返回 value。在调试模式下（即未定义 NDEBUG），如果 value 与为 Bar 定义的任何值都不匹配，则此方法将中止进程。
  • void clear_bar()：清除字段的值。调用此方法后，has_bar() 将返回 false，bar() 将返回默认值。

隐式存在枚举字段（proto3）

给定枚举类型

enum Bar {
  BAR_UNSPECIFIED = 0;
  BAR_VALUE = 1;
  BAR_OTHER_VALUE = 2;
}

对于此字段定义

Bar bar = 1;  // no field label specified, defaults to implicit presence.

编译器将生成以下访问器方法

  • Bar bar() const：返回字段的当前值。如果字段未设置，则返回默认值 (0)。
  • void set_bar(Bar value)：设置字段的值。调用此方法后，bar() 将返回 value。
  • void clear_bar()：清除字段的值。调用此方法后，bar() 将返回默认值。

可选嵌入消息字段（proto2 和 proto3）

给定消息类型

message Bar {}

对于以下任何字段定义

//proto2
optional Bar bar = 1;
required Bar bar = 1;

//proto3
Bar bar = 1;

编译器将生成以下访问器方法

  • bool has_bar() const：如果字段已设置，则返回 true。
  • const Bar& bar() const：返回字段的当前值。如果字段未设置，则返回一个未设置任何字段的 Bar（可能是 Bar::default_instance()）。
  • Bar* mutable_bar()：返回指向存储字段值的可变 Bar 对象的指针。如果在调用之前字段未设置，则返回的 Bar 将不设置任何字段（即，它将与新分配的 Bar 相同）。调用此方法后，has_bar() 将返回 true，bar() 将返回对同一 Bar 实例的引用。
  • void clear_bar()：清除字段的值。调用此方法后，has_bar() 将返回 false，bar() 将返回默认值。
  • void set_allocated_bar(Bar* bar)：将 Bar 对象设置为字段，并释放以前的字段值（如果存在）。如果 Bar 指针不是 NULL，则消息将获得已分配的 Bar 对象的所有权，并且 has_bar() 将返回 true。否则，如果 Bar 为 NULL，则行为与调用 clear_bar() 相同。
  • Bar* release_bar()：释放字段的所有权并返回 Bar 对象的指针。调用此方法后，调用者将获得已分配的 Bar 对象的所有权，has_bar() 将返回 false，bar() 将返回默认值。

重复数值字段

对于此字段定义

repeated int32 foo = 1;

编译器将生成以下访问器方法

  • int foo_size() const：返回字段中当前元素的数量。要检查是否为空集，请考虑使用底层 RepeatedField 中的 empty() 方法，而不是此方法。
  • int32 foo(int index) const：返回给定从零开始的索引处的元素。使用 [0, foo_size()) 之外的索引调用此方法会产生未定义的行为。
  • void set_foo(int index, int32 value)：设置给定从零开始的索引处的元素的值。
  • void add_foo(int32 value)：将一个新元素追加到字段的末尾，并赋予给定的值。
  • void clear_foo()：从字段中删除所有元素。调用此方法后，foo_size() 将返回零。
  • const RepeatedField<int32>& foo() const：返回存储字段元素的底层 RepeatedField。此容器类提供类似 STL 的迭代器和其他方法。
  • RepeatedField<int32>* mutable_foo()：返回指向存储字段元素的可变底层 RepeatedField 的指针。此容器类提供类似 STL 的迭代器和其他方法。

对于其他数值字段类型（包括 bool），int32 将根据 标量值类型表 替换为相应的 C++ 类型。

重复字符串字段

注意： 从 2023 版本开始，如果 features.(pb.cpp).string_type 设置为 VIEW，则将生成 string_view API。

对于以下任一字段定义

repeated string foo = 1;
repeated bytes foo = 1;

编译器将生成以下访问器方法

  • int foo_size() const：返回字段中当前元素的数量。要检查是否为空集，请考虑使用底层 RepeatedField 中的 empty() 方法，而不是此方法。
  • const string& foo(int index) const：返回给定从零开始的索引处的元素。使用 [0, foo_size()-1] 之外的索引调用此方法会产生未定义的行为。
  • void set_foo(int index, ::absl::string_view value)：设置给定从零开始的索引处的元素的值。
  • void set_foo(int index, const string& value)：设置给定从零开始的索引处的元素的值。
  • void set_foo(int index, string&& value)：设置给定从零开始的索引处的元素的值，从传递的字符串移动。
  • void set_foo(int index, const char* value)：使用 C 风格的空终止字符串设置给定从零开始的索引处的元素的值。
  • void set_foo(int index, const char* value, int size)：使用 C 风格的字符串（显式指定大小，而不是通过查找空终止符字节确定）设置给定从零开始的索引处的元素的值。
  • string* mutable_foo(int index)：返回指向存储给定从零开始的索引处的元素值的可变 string 对象的指针。使用 [0, foo_size()) 之外的索引调用此方法会产生未定义的行为。
  • void add_foo(::absl::string_view value)：将一个新元素追加到给定从零开始的索引处的元素的末尾。
  • void add_foo(const string& value)：将一个新元素追加到字段的末尾，并赋予给定的值。
  • void add_foo(string&& value)：将一个新元素追加到字段的末尾，从传递的字符串移动。
  • void add_foo(const char* value)：使用 C 风格的空终止字符串将一个新元素追加到字段的末尾。
  • void add_foo(const char* value, int size)：使用字符串（显式指定大小，而不是通过查找空终止符字节确定）将一个新元素追加到字段的末尾。
  • string* add_foo()：向字段的末尾添加一个新的空字符串元素，并返回指向它的指针。
  • void clear_foo()：从字段中删除所有元素。调用此方法后，foo_size() 将返回零。
  • const RepeatedPtrField<string>& foo() const：返回存储字段元素的底层 RepeatedPtrField。此容器类提供类似 STL 的迭代器和其他方法。
  • RepeatedPtrField<string>* mutable_foo()：返回指向存储字段元素的可变底层 RepeatedPtrField 的指针。此容器类提供类似 STL 的迭代器和其他方法。

重复枚举字段

给定枚举类型

enum Bar {
  BAR_UNSPECIFIED = 0;
  BAR_VALUE = 1;
  BAR_OTHER_VALUE = 2;
}

对于此字段定义

repeated Bar bar = 1;

编译器将生成以下访问器方法

  • int bar_size() const：返回字段中当前元素的数量。要检查是否为空集，请考虑使用底层 RepeatedField 中的 empty() 方法，而不是此方法。
  • Bar bar(int index) const：返回给定从零开始的索引处的元素。使用 [0, bar_size()) 之外的索引调用此方法会产生未定义的行为。
  • void set_bar(int index, Bar value)：设置给定从零开始的索引处的元素的值。在调试模式下（即未定义 NDEBUG），如果 value 与为 Bar 定义的任何值都不匹配，则此方法将中止进程。
  • void add_bar(Bar value)：将一个新元素追加到字段的末尾，并赋予给定的值。在调试模式下（即未定义 NDEBUG），如果 value 与为 Bar 定义的任何值都不匹配，则此方法将中止进程。
  • void clear_bar()：从字段中删除所有元素。调用此方法后，bar_size() 将返回零。
  • const RepeatedField<int>& bar() const：返回存储字段元素的底层 RepeatedField。此容器类提供类似 STL 的迭代器和其他方法。
  • RepeatedField<int>* mutable_bar()：返回指向存储字段元素的可变底层 RepeatedField 的指针。此容器类提供类似 STL 的迭代器和其他方法。

重复嵌入消息字段

给定消息类型

message Bar {}

对于此字段定义

repeated Bar bar = 1;

编译器将生成以下访问器方法

  • int bar_size() const：返回字段中当前元素的数量。要检查是否为空集，请考虑使用底层 RepeatedField 中的 empty() 方法，而不是此方法。
  • const Bar& bar(int index) const：返回给定从零开始的索引处的元素。使用 [0, bar_size()) 之外的索引调用此方法会产生未定义的行为。
  • Bar* mutable_bar(int index)：返回指向存储给定从零开始的索引处的元素值的可变 Bar 对象的指针。使用 [0, bar_size()) 之外的索引调用此方法会产生未定义的行为。
  • Bar* add_bar()：向字段的末尾添加一个新元素，并返回指向它的指针。返回的 Bar 是可变的，并且不会设置任何字段（即，它将与新分配的 Bar 相同）。
  • void clear_bar()：从字段中删除所有元素。调用此方法后，bar_size() 将返回零。
  • const RepeatedPtrField<Bar>& bar() const：返回存储字段元素的底层 RepeatedPtrField。此容器类提供类似 STL 的迭代器和其他方法。
  • RepeatedPtrField<Bar>* mutable_bar()：返回指向存储字段元素的可变底层 RepeatedPtrField 的指针。此容器类提供类似 STL 的迭代器和其他方法。

Oneof 数值字段

对于此 oneof 字段定义

oneof example_name {
    int32 foo = 1;
    ...
}

编译器将生成以下访问器方法

  • bool has_foo() const：如果 oneof case 是 kFoo，则返回 true。
  • int32 foo() const：如果 oneof case 是 kFoo，则返回字段的当前值。否则，返回默认值。
  • void set_foo(int32 value):
    • 如果设置了同一 oneof 中的任何其他 oneof 字段，则调用 clear_example_name()。
    • 设置此字段的值并将 oneof case 设置为 kFoo。
    • has_foo() 将返回 true，foo() 将返回 value，并且 example_name_case() 将返回 kFoo。
  • void clear_foo():
    • 如果 oneof case 不是 kFoo，则不会更改任何内容。
    • 如果 oneof case 是 kFoo，则清除字段的值和 oneof case。 has_foo() 将返回 false，foo() 将返回默认值，并且 example_name_case() 将返回 EXAMPLE_NAME_NOT_SET。

对于其他数值字段类型（包括 bool），int32 将根据 标量值类型表 替换为相应的 C++ 类型。

Oneof 字符串字段

注意： 从 2023 版本开始，可能会生成 string_view API

对于以下任何 oneof 字段定义

oneof example_name {
    string foo = 1;
    ...
}
oneof example_name {
    bytes foo = 1;
    ...
}

编译器将生成以下访问器方法

  • bool has_foo() const：如果 oneof case 是 kFoo，则返回 true。
  • const string& foo() const：如果 oneof case 是 kFoo，则返回字段的当前值。否则，返回默认值。
  • void set_foo(::absl::string_view value):
    • 如果设置了同一 oneof 中的任何其他 oneof 字段，则调用 clear_example_name()。
    • 设置此字段的值并将 oneof case 设置为 kFoo。
    • has_foo() 将返回 true，foo() 将返回 value 的副本，并且 example_name_case() 将返回 kFoo。
  • void set_foo(const string& value)：与第一个 set_foo() 类似，但从 const string 引用复制。
  • void set_foo(string&& value)：与第一个 set_foo() 类似，但从传递的字符串移动。
  • void set_foo(const char* value)：与第一个 set_foo() 类似，但从 C 风格的空终止字符串复制。
  • void set_foo(const char* value, int size)：与第一个 set_foo() 类似，但从显式指定大小的字符串（而不是通过查找空终止符字节确定）复制。
  • string* mutable_foo():
    • 如果设置了同一 oneof 中的任何其他 oneof 字段，则调用 clear_example_name()。
    • 将 oneof case 设置为 kFoo，并返回指向存储字段值的可变字符串对象的指针。如果 oneof case 在调用之前不是 kFoo，则返回的字符串将为空（不是默认值）。
    • has_foo() 将返回 true，foo() 将返回写入给定字符串的任何值，并且 example_name_case() 将返回 kFoo。
  • void clear_foo():
    • 如果 oneof case 不是 kFoo，则不会更改任何内容。
    • 如果 oneof case 是 kFoo，则释放字段并清除 oneof case。 has_foo() 将返回 false，foo() 将返回默认值，并且 example_name_case() 将返回 EXAMPLE_NAME_NOT_SET。
  • void set_allocated_foo(string* value):
    • 调用 clear_example_name()。
    • 如果字符串指针不是 NULL：将字符串对象设置为该字段，并将 oneof case 设置为 kFoo。消息取得已分配字符串对象的所有权，has_foo() 将返回 true，example_name_case() 将返回 kFoo。
    • 如果字符串指针是 NULL，has_foo() 将返回 false，example_name_case() 将返回 EXAMPLE_NAME_NOT_SET。
  • string* release_foo():
    • 如果 oneof case 不是 kFoo，则返回 NULL。
    • 清除 oneof case，释放字段的所有权，并返回字符串对象的指针。调用此方法后，调用者取得已分配字符串对象的所有权，has_foo() 将返回 false，foo() 将返回默认值，并且 example_name_case() 将返回 EXAMPLE_NAME_NOT_SET。

Oneof 枚举字段

给定枚举类型

enum Bar {
  BAR_UNSPECIFIED = 0;
  BAR_VALUE = 1;
  BAR_OTHER_VALUE = 2;
}

对于 oneof 字段定义

oneof example_name {
    Bar bar = 1;
    ...
}

编译器将生成以下访问器方法

  • bool has_bar() const：如果 oneof case 是 kBar，则返回 true。
  • Bar bar() const：如果 oneof case 是 kBar，则返回该字段的当前值。否则，返回默认值。
  • void set_bar(Bar value):
    • 如果设置了同一 oneof 中的任何其他 oneof 字段，则调用 clear_example_name()。
    • 设置此字段的值，并将 oneof case 设置为 kBar。
    • has_bar() 将返回 true，bar() 将返回 value，并且 example_name_case() 将返回 kBar。
    • 在调试模式（即未定义 NDEBUG）下，如果 value 与为 Bar 定义的任何值都不匹配，则此方法将中止进程。
  • void clear_bar():
    • 如果 oneof case 不是 kBar，则不会进行任何更改。
    • 如果 oneof case 是 kBar，则清除该字段的值和 oneof case。has_bar() 将返回 false，bar() 将返回默认值，并且 example_name_case() 将返回 EXAMPLE_NAME_NOT_SET。

Oneof 嵌入消息字段

给定消息类型

message Bar {}

对于 oneof 字段定义

oneof example_name {
    Bar bar = 1;
    ...
}

编译器将生成以下访问器方法

  • bool has_bar() const：如果 oneof case 是 kBar，则返回 true。
  • const Bar& bar() const：如果 oneof case 是 kBar，则返回该字段的当前值。否则，返回一个没有设置任何字段的 Bar（可能是 Bar::default_instance()）。
  • Bar* mutable_bar():
    • 如果设置了同一 oneof 中的任何其他 oneof 字段，则调用 clear_example_name()。
    • 将 oneof case 设置为 kBar，并返回指向存储字段值的可变 Bar 对象的指针。如果在调用之前 oneof case 不是 kBar，则返回的 Bar 将没有任何字段设置（即，它将与新分配的 Bar 相同）。
    • 调用此方法后，has_bar() 将返回 true，bar() 将返回对 Bar 同一实例的引用，并且 example_name_case() 将返回 kBar。
  • void clear_bar():
    • 如果 oneof case 不是 kBar，则不会进行任何更改。
    • 如果 oneof case 等于 kBar，则释放该字段并清除 oneof case。has_bar() 将返回 false，bar() 将返回默认值，并且 example_name_case() 将返回 EXAMPLE_NAME_NOT_SET。
  • void set_allocated_bar(Bar* bar):
    • 调用 clear_example_name()。
    • 如果 Bar 指针不是 NULL：将 Bar 对象设置为该字段，并将 oneof case 设置为 kBar。消息取得已分配 Bar 对象的所有权，has_bar() 将返回 true，example_name_case() 将返回 kBar。
    • 如果指针是 NULL，has_bar() 将返回 false，example_name_case() 将返回 EXAMPLE_NAME_NOT_SET。（行为类似于调用 clear_example_name()）
  • Bar* release_bar():
    • 如果 oneof case 不是 kBar，则返回 NULL。
    • 如果 oneof case 是 kBar，则清除 oneof case，释放字段的所有权，并返回 Bar 对象的指针。调用此方法后，调用者取得已分配 Bar 对象的所有权，has_bar() 将返回 false，bar() 将返回默认值，并且 example_name_case() 将返回 EXAMPLE_NAME_NOT_SET。

Map 字段

对于此 map 字段定义

map<int32, int32> weight = 1;

编译器将生成以下访问器方法

  • const google::protobuf::Map<int32, int32>& weight();：返回一个不可变 Map。
  • google::protobuf::Map<int32, int32>* mutable_weight();：返回一个可变 Map。

google::protobuf::Map 是协议缓冲区中使用的一种特殊容器类型，用于存储 map 字段。正如您可以从下面的接口中看到的那样，它使用了 std::map 和 std::unordered_map 方法中常用的子集。

template<typename Key, typename T> {
class Map {
  // Member types
  typedef Key key_type;
  typedef T mapped_type;
  typedef MapPair< Key, T > value_type;

  // Iterators
  iterator begin();
  const_iterator begin() const;
  const_iterator cbegin() const;
  iterator end();
  const_iterator end() const;
  const_iterator cend() const;
  // Capacity
  int size() const;
  bool empty() const;

  // Element access
  T& operator[](const Key& key);
  const T& at(const Key& key) const;
  T& at(const Key& key);

  // Lookup
  bool contains(const Key& key) const;
  int count(const Key& key) const;
  const_iterator find(const Key& key) const;
  iterator find(const Key& key);

  // Modifiers
  pair<iterator, bool> insert(const value_type& value);
  template<class InputIt>
  void insert(InputIt first, InputIt last);
  size_type erase(const Key& Key);
  iterator erase(const_iterator pos);
  iterator erase(const_iterator first, const_iterator last);
  void clear();

  // Copy
  Map(const Map& other);
  Map& operator=(const Map& other);
}

添加数据的最简单方法是使用普通的 map 语法，例如

std::unique_ptr<ProtoName> my_enclosing_proto(new ProtoName);
(*my_enclosing_proto->mutable_weight())[my_key] = my_value;

pair<iterator, bool> insert(const value_type& value) 将隐式地导致 value_type 实例的深拷贝。将新值插入 google::protobuf::Map 的最有效方法如下

T& operator[](const Key& key): map[new_key] = new_mapped;

将 google::protobuf::Map 与标准 map 一起使用

google::protobuf::Map 支持与 std::map 和 std::unordered_map 相同的迭代器 API。如果您不想直接使用 google::protobuf::Map，则可以通过执行以下操作将 google::protobuf::Map 转换为标准 map

std::map<int32, int32> standard_map(message.weight().begin(),
                                    message.weight().end());

请注意，这将对整个 map 进行深拷贝。

您还可以从标准 map 构造 google::protobuf::Map，如下所示

google::protobuf::Map<int32, int32> weight(standard_map.begin(), standard_map.end());

解析未知值

在网络传输中，.proto map 相当于每个键/值对的 map 条目消息，而 map 本身是 map 条目的 repeated 字段。与普通消息类型一样，已解析的 map 条目消息可能具有未知字段：例如，在定义为 map<int32, string> 的 map 中，类型为 int64 的字段。

如果 map 条目消息的网络格式中存在未知字段，则会将其丢弃。

如果 map 条目消息的网络格式中存在未知的枚举值，则在 proto2 和 proto3 中的处理方式不同。在 proto2 中，整个 map 条目消息都放入包含消息的未知字段集中。在 proto3 中，它被放入 map 字段中，就好像它是一个已知的枚举值一样。

Any

给定一个 Any 字段，例如

import "google/protobuf/any.proto";

message ErrorStatus {
  string message = 1;
  google.protobuf.Any details = 2;
}

在我们生成的代码中，details 字段的 getter 返回 google::protobuf::Any 的实例。这提供了以下特殊方法来打包和解包 Any 的值

class Any {
 public:
  // Packs the given message into this Any using the default type URL
  // prefix “type.googleapis.com”. Returns false if serializing the message failed.
  bool PackFrom(const google::protobuf::Message& message);

  // Packs the given message into this Any using the given type URL
  // prefix. Returns false if serializing the message failed.
  bool PackFrom(const google::protobuf::Message& message,
                ::absl::string_view type_url_prefix);

  // Unpacks this Any to a Message. Returns false if this Any
  // represents a different protobuf type or parsing fails.
  bool UnpackTo(google::protobuf::Message* message) const;

  // Returns true if this Any represents the given protobuf type.
  template<typename T> bool Is() const;
}

Oneof

给定一个 oneof 定义，例如

oneof example_name {
    int32 foo_int = 4;
    string foo_string = 9;
    ...
}

编译器将生成以下 C++ 枚举类型

enum ExampleNameCase {
  kFooInt = 4,
  kFooString = 9,
  EXAMPLE_NAME_NOT_SET = 0
}

此外，它将生成这些方法

  • ExampleNameCase example_name_case() const：返回指示设置了哪个字段的枚举。如果未设置任何字段，则返回 EXAMPLE_NAME_NOT_SET。
  • void clear_example_name()：如果 oneof 字段集使用指针（Message 或 String），则释放对象，并将 oneof case 设置为 EXAMPLE_NAME_NOT_SET。

枚举

注意： 从 2024 年版开始，可能会使用某些功能设置生成 string_view API。有关此主题的更多信息，请参阅 枚举名称助手。

给定一个枚举定义，例如

enum Foo {
  VALUE_A = 0;
  VALUE_B = 5;
  VALUE_C = 1234;
}

协议缓冲区编译器将生成一个名为 Foo 的 C++ 枚举类型，其中包含相同的值集。此外，编译器将生成以下函数

  • const EnumDescriptor* Foo_descriptor()：返回类型的描述符，其中包含有关此枚举类型定义了哪些值的信息。
  • bool Foo_IsValid(int value)：如果给定的数值与 Foo 定义的值之一匹配，则返回 true。在上面的示例中，如果输入为 0、5 或 1234，则它将返回 true。
  • const string& Foo_Name(int value)：返回给定数值的名称。如果不存在这样的值，则返回空字符串。如果多个值具有此数字，则返回定义的第一个值。在上面的示例中，Foo_Name(5) 将返回 "VALUE_B"。
  • bool Foo_Parse(::absl::string_view name, Foo* value)：如果 name 是此枚举的有效值名称，则将该值分配给 value 并返回 true。否则返回 false。在上面的示例中，Foo_Parse("VALUE_C", &some_foo) 将返回 true 并将 some_foo 设置为 1234。
  • const Foo Foo_MIN：枚举的最小有效值（示例中的 VALUE_A）。
  • const Foo Foo_MAX：枚举的最大有效值（示例中的 VALUE_C）。
  • const int Foo_ARRAYSIZE：始终定义为 Foo_MAX + 1。

将整数强制转换为 proto2 枚举时要小心。 如果将整数强制转换为 proto2 枚举值，则该整数必须是该枚举的有效值之一，否则结果可能是未定义的。如果对此有疑问，请使用生成的 Foo_IsValid() 函数来测试强制转换是否有效。将 proto2 消息的枚举类型字段设置为无效值可能会导致断言失败。如果在解析 proto2 消息时读取到无效的枚举值，则会将其视为未知字段。这些语义已在 proto3 中更改。只要整数适合 int32，就可以安全地将任何整数强制转换为 proto3 枚举值。解析 proto3 消息时，无效的枚举值也将被保留，并由枚举字段访问器返回。

在 switch 语句中使用 proto3 枚举时要小心。 Proto3 枚举是开放枚举类型，可能的值超出指定符号的范围。解析 proto3 消息时，无法识别的枚举值将被保留，并由枚举字段访问器返回。即使列出了所有已知字段，在没有 default 分支的情况下对 proto3 枚举进行 switch 语句也无法捕获所有情况。这可能会导致意外行为，包括数据损坏和运行时崩溃。始终添加 default 分支或在 switch 外部显式调用 Foo_IsValid(int) 以处理未知枚举值。

您可以在消息类型内部定义枚举。在这种情况下，协议缓冲区编译器生成的代码使其看起来枚举类型本身是在消息类的内部声明的。Foo_descriptor() 和 Foo_IsValid() 函数声明为静态方法。实际上，枚举类型本身及其值是在全局作用域中声明的，并带有混淆名称，并通过 typedef 和一系列常量定义导入到类的作用域中。这样做只是为了解决声明顺序问题。不要依赖混淆的顶层名称；假装枚举确实嵌套在消息类中。

扩展（仅限 proto2）

给定一个带有扩展范围的消息

message Foo {
  extensions 100 to 199;
}

协议缓冲区编译器将为 Foo 生成一些附加方法：HasExtension()、ExtensionSize()、ClearExtension()、GetExtension()、SetExtension()、MutableExtension()、AddExtension()、SetAllocatedExtension() 和 ReleaseExtension()。这些方法中的每一种都将其第一个参数作为扩展标识符（如下所述），该标识符标识一个扩展字段。其余参数和返回值与为与扩展标识符类型相同的普通（非扩展）字段生成的相应访问器方法完全相同。（GetExtension() 对应于没有特殊前缀的访问器。）

给定一个扩展定义

extend Foo {
  optional int32 bar = 123;
  repeated int32 repeated_bar = 124;
  optional Bar message_bar = 125;
}

对于单数扩展字段 bar，协议缓冲区编译器生成一个名为 bar 的“扩展标识符”，您可以将其与 Foo 的扩展访问器一起使用来访问此扩展，如下所示

Foo foo;
assert(!foo.HasExtension(bar));
foo.SetExtension(bar, 1);
assert(foo.HasExtension(bar));
assert(foo.GetExtension(bar) == 1);
foo.ClearExtension(bar);
assert(!foo.HasExtension(bar));

对于消息扩展字段 message_bar，如果未设置该字段，则 foo.GetExtension(message_bar) 返回一个没有设置任何字段的 Bar（可能是 Bar::default_instance()）。

同样，对于 repeated 扩展字段 repeated_bar，编译器生成一个名为 repeated_bar 的扩展标识符，您也可以将其与 Foo 的扩展访问器一起使用

Foo foo;
for (int i = 0; i < kSize; ++i) {
  foo.AddExtension(repeated_bar, i)
}
assert(foo.ExtensionSize(repeated_bar) == kSize)
for (int i = 0; i < kSize; ++i) {
  assert(foo.GetExtension(repeated_bar, i) == i)
}

（扩展标识符的确切实现很复杂，并且涉及模板的奇妙用法——但是，您无需担心扩展标识符的工作原理即可使用它们。）

扩展可以声明为嵌套在另一种类型内部。例如，一种常见的模式是执行如下操作

message Baz {
  extend Foo {
    optional Baz foo_ext = 124;
  }
}

在这种情况下，扩展标识符 foo_ext 声明为嵌套在 Baz 内部。它可以按如下方式使用

Foo foo;
Baz* baz = foo.MutableExtension(Baz::foo_ext);
FillInMyBaz(baz);

Arena 分配

Arena 分配是一项仅 C++ 功能，可帮助您优化内存使用并提高使用协议缓冲区时的性能。在您的 .proto 中启用 arena 分配会为您的 C++ 生成代码添加用于使用 arena 的附加代码。您可以在 Arena 分配指南中找到有关 arena 分配 API 的更多信息。

服务

如果 .proto 文件包含以下行

option cc_generic_services = true;

那么协议缓冲区编译器将根据文件中找到的服务定义生成代码，如本节所述。但是，生成的代码可能是不理想的，因为它未绑定到任何特定的 RPC 系统，因此比为单个系统量身定制的代码需要更多的间接级别。如果您不希望生成此代码，请将此行添加到文件中

option cc_generic_services = false;

如果未给出以上任何一行，则该选项默认为 false，因为通用服务已弃用。（请注意，在 2.4.0 之前，该选项默认为 true）

基于 .proto 语言服务定义的 RPC 系统应提供 插件，以生成适合该系统的代码。这些插件可能需要禁用抽象服务，以便它们可以生成具有相同名称的自己的类。

本节的其余部分描述了在启用抽象服务时协议缓冲区编译器生成的内容。

接口

给定一个服务定义

service Foo {
  rpc Bar(FooRequest) returns(FooResponse);
}

协议缓冲区编译器将生成一个类 Foo 来表示此服务。Foo 将为服务定义中定义的每个方法都有一个虚方法。在这种情况下，方法 Bar 定义为

virtual void Bar(RpcController* controller, const FooRequest* request,
                 FooResponse* response, Closure* done);

这些参数等效于 Service::CallMethod() 的参数，不同之处在于 method 参数是隐含的，而 request 和 response 指定了它们的精确类型。

这些生成的方法是虚方法，但不是纯虚方法。默认实现只是使用指示该方法未实现的错误消息调用 controller->SetFailed()，然后调用 done 回调。在实现您自己的服务时，您必须子类化此生成的服务并根据需要实现其方法。

Foo 子类化了 Service 接口。协议缓冲区编译器自动生成 Service 方法的实现，如下所示

  • GetDescriptor：返回服务的 ServiceDescriptor。
  • CallMethod：根据提供的方法描述符确定正在调用的方法，并直接调用它，将请求和响应消息对象向下转换为正确的类型。
  • GetRequestPrototype 和 GetResponsePrototype：返回给定方法的正确类型的请求或响应的默认实例。

还生成以下静态方法

  • static ServiceDescriptor descriptor()：返回类型的描述符，其中包含有关此服务具有哪些方法以及它们的输入和输出类型的信息。

存根

协议缓冲区编译器还为每个服务接口生成一个“桩”实现，客户端希望使用该实现向实现该服务的服务器发送请求。对于 Foo 服务（如上所述），将定义桩实现 Foo_Stub。与嵌套消息类型一样，使用 typedef，以便 Foo_Stub 也可以称为 Foo::Stub。

Foo_Stub 是 Foo 的子类，它还实现了以下方法

  • Foo_Stub(RpcChannel* channel)：构造一个新的桩，该桩在给定的通道上发送请求。
  • Foo_Stub(RpcChannel* channel, ChannelOwnership ownership)：构造一个新的桩，该桩在给定的通道上发送请求，并可能拥有该通道。如果 ownership 是 Service::STUB_OWNS_CHANNEL，则在删除桩对象时，它也会删除该通道。
  • RpcChannel* channel()：返回此桩的通道，如传递给构造函数的那样。

桩还为每个服务的方法实现了一个围绕通道的包装器。调用其中一种方法只会调用 channel->CallMethod()。

Protocol Buffer 库不包含 RPC 实现。但是，它包含了将生成的服务类连接到您选择的任何任意 RPC 实现所需的所有工具。您只需要提供 RpcChannel 和 RpcController 的实现即可。有关更多信息，请参阅 service.h 的文档。

插件插入点

代码生成器插件，它们希望扩展 C++ 代码生成器的输出，可以使用给定的插入点名称插入以下类型的代码。每个插入点都出现在 .pb.cc 文件和 .pb.h 文件中，除非另有说明。

  • includes：包含指令。
  • namespace_scope：属于文件的包/命名空间但不属于任何特定类的声明。出现在所有其他命名空间作用域代码之后。
  • global_scope：属于顶层（文件命名空间之外）的声明。出现在文件的末尾。
  • class_scope:TYPENAME：属于消息类的成员声明。TYPENAME 是完整的 proto 名称，例如 package.MessageType。出现在类中的所有其他公共声明之后。此插入点仅出现在 .pb.h 文件中。

不要生成依赖于标准代码生成器声明的私有类成员的代码，因为这些实现细节可能会在 Protocol Buffers 的未来版本中更改。