C++ 生成代码指南

详细描述了 protocol buffer 编译器针对任何给定的协议定义所生成的 C++ 代码。

本文档重点说明了 proto2、proto3 和 editions 生成代码之间的任何差异。请注意，这些差异存在于本文档描述的生成代码中，而不是在所有版本中都相同的基础消息类/接口中。在阅读本文档之前，您应该先阅读 proto2 语言指南、proto3 语言指南 或 edition 2023 语言指南。

编译器调用

当使用 --cpp_out= 命令行标志调用时，protocol buffer 编译器会生成 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；它们必须已经存在。

包（Packages）

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

package foo.bar;

文件中的所有声明都将位于 foo::bar 命名空间中。

消息

给定一个简单的消息声明：

message Foo {}

protocol buffer 编译器会生成一个名为 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*。

注意： 拷贝构造函数和赋值运算符执行消息数据的深拷贝。这确保了每个消息对象都拥有并管理其自身的数据副本，防止了诸如双重释放或使用后释放之类的错误。这种行为与标准 C++ 中拥有其数据的对象（例如 std::vector）的实践是一致的。对于来自具有不同拷贝语义的语言（例如 JavaScript 或 TypeScript，其中浅拷贝可能更常见）的开发者来说，需要注意的是，对拷贝后的消息的修改不会影响原始消息，反之亦然。

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

  • static const Descriptor* descriptor()：返回类型的描述符。这包含了关于类型的信息，包括它有哪些字段以及它们的类型是什么。这可以与反射一起使用，以编程方式检查字段。
  • static const Foo& default_instance()：返回一个 Foo 的常量单例实例，它与一个新构造的 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。

字段

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

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

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

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

显式存在性数字字段

对于具有显式存在性的数字字段的字段定义：

int32 foo = 1;

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

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

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

隐式存在性数字字段

对于具有隐式存在性的数字字段的字段定义：

int32 foo = 1;

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

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

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

显式存在性字符串/字节字段

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

对于这些具有显式存在性的字段定义：

string foo = 1;
bytes foo = 2;

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

  • bool has_foo() const：如果字段已设置，则返回 true。

  • const string& foo() const：返回字段的当前值。如果字段未设置，则返回默认值。

  • void set_foo(...)：设置字段的值。调用此方法后，has_foo() 将返回 true，foo() 将返回 value 的副本。

  • string* mutable_foo()：返回一个指向存储字段值的可变 string 对象的指针。如果在调用前该字段未设置，则返回的字符串将为空（*不是*默认值）。调用此方法后，has_foo() 将返回 true，foo() 将返回写入给定字符串的任何值。

    注意： 此方法将在新的 string_view API 中被移除。

  • 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() 将返回默认值。

隐式存在性字符串/字节字段

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

对于这些具有隐式存在性的字段定义：

string foo = 1 [features.field_presence = IMPLICIT];
bytes foo = 1 [features.field_presence = IMPLICIT];

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

  • const string& foo() const：返回字段的当前值。如果字段未设置，则返回空字符串/空字节。
  • void set_foo(Arg_&& arg, Args_... args)：设置字段的值。调用此方法后，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 存储数据，请使用以下语法：

// edition (default settings)
bytes foo = 25 [ctype=CORD];
bytes foo = 26 [ctype=CORD, features.field_presence = IMPLICIT];

对于 repeated bytes 字段，无法使用 cord。Protoc 会忽略这些字段上的 [ctype=CORD] 设置。

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

  • const ::absl::Cord& foo() const：返回字段的当前值。如果字段未设置，则返回一个空的 Cord（proto3）或默认值（proto2 和 editions）。
  • 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 和 editions）。
  • bool has_foo()：如果字段已设置，则返回 true。仅适用于 proto3 中的 optional 字段和 editions 中的显式存在性字段。

显式存在性枚举字段

给定枚举类型：

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

对于此具有显式存在性的字段定义：

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() 将返回默认值。

隐式存在性枚举字段

给定枚举类型：

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

对于此具有隐式存在性的字段定义：

Bar bar = 1;

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

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

显式存在性内嵌消息字段

给定消息类型：

message Bar {}

对于此具有显式存在性的字段定义：

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* value)：将 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_t foo(int index) const：返回给定从零开始的索引处的元素。使用超出 [0, foo_size()) 范围的索引调用此方法会产生未定义行为。
  • void set_foo(int index, int32_t value)：设置给定从零开始的索引处元素的值。
  • void add_foo(int32_t value)：在字段末尾追加一个具有给定值的新元素。
  • void clear_foo()：从字段中移除所有元素。调用此方法后，foo_size() 将返回零。
  • const RepeatedField<int32_t>& foo() const：返回存储字段元素的底层 RepeatedField。此类容器提供了类似 STL 的迭代器和其他方法。
  • RepeatedField<int32_t>* mutable_foo()：返回一个指向存储字段元素的底层可变 RepeatedField 的指针。此类容器提供了类似 STL 的迭代器和其他方法。

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

重复字符串字段

注意： 从 edition 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 风格的以 null 结尾的字符串设置给定从零开始的索引处元素的值。
  • void set_foo(int index, const char* value, int size)：使用指定了显式大小的 C 风格字符串设置给定从零开始的索引处元素的值，而不是通过查找 null 终止符字节来确定大小。
  • 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 风格的以 null 结尾的字符串在字段末尾追加一个新元素。
  • void add_foo(const char* value, int size)：使用指定了显式大小的字符串在字段末尾追加一个新元素，而不是通过查找 null 终止符字节来确定大小。
  • 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 中的任何其他字段已设置，则调用 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_t 会根据标量值类型表替换为相应的 C++ 类型。

Oneof 字符串字段

注意： 从 edition 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 中的任何其他字段已设置，则调用 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 风格的以 null 结尾的字符串复制。
  • void set_foo(const char* value, int size)：与第一个 set_foo() 类似，但从指定了显式大小的字符串复制，而不是通过查找 null 终止符字节来确定大小。
  • string* mutable_foo():
    • 如果同一个 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 中的任何其他字段已设置，则调用 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 中的任何其他字段已设置，则调用 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 是 protocol buffers 中用于存储 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 条目的重复字段。与普通消息类型一样，解析后的 map 条目消息可能包含未知字段：例如，在定义为 map<int32, string> 的 map 中出现一个类型为 int64 的字段。

如果 map 条目消息的在线格式中存在未知字段，它们将被丢弃。

如果 map 条目消息的在线格式中存在未知的枚举值，则在 proto2、proto3 和 editions 中的处理方式不同。在 proto2 中，整个 map 条目消息被放入包含消息的未知字段集中。在 proto3 中，它被放入一个 map 字段中，就好像它是一个已知的枚举值一样。对于 editions，默认情况下它镜像 proto3 的行为。如果 features.enum_type 设置为 CLOSED，则它镜像 proto2 的行为。

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 字段使用指针（消息或字符串），则释放该对象，并将 oneof case 设置为 EXAMPLE_NAME_NOT_SET。

枚举

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

给定一个枚举定义，例如：

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

protocol buffer 编译器将生成一个名为 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 和 editions 枚举时要小心。 Proto3 和 editions 枚举是开放枚举类型，其可能的值超出了指定符号的范围。（使用 enum_type 功能可以将 Editions 枚举设置为封闭枚举。）对于开放枚举类型，未识别的枚举值在解析消息时将被保留，并由枚举字段访问器返回。在开放枚举上没有默认情况的 switch 语句将无法捕获所有情况，即使列出了所有已知字段也是如此。这可能导致意外行为，包括数据损坏和运行时崩溃。始终添加一个默认情况或在 switch 外部显式调用 Foo_IsValid(int) 来处理未知的枚举值。

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

扩展（仅限 proto2 和 editions）

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

message Foo {
  extensions 100 to 199;
}

protocol buffer 编译器将为 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，protocol buffer 编译器会生成一个名为 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_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++ 独有的功能，可帮助您在处理 protocol buffers 时优化内存使用并提高性能。在您的 .proto 中启用 arena 分配会为您的 C++ 生成代码添加用于处理 arena 的额外代码。您可以在Arena 分配指南中找到有关 arena 分配 API 的更多信息。

服务（Services）

如果 .proto 文件包含以下行：

option cc_generic_services = true;

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

option cc_generic_services = false;

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

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

本节的其余部分描述了当启用抽象服务时，protocol buffer 编译器会生成什么。

接口

给定一个服务定义：

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

protocol buffer 编译器将生成一个名为 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 接口。protocol buffer 编译器自动生成了 Service 方法的实现，如下所示：

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

还生成了以下静态方法：

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

Stub

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

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

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

stub 还将每个服务方法实现为对通道的包装。调用其中一个方法只是调用 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 中发生变化。