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)：从给定的序列化二进制字符串（也称为 wire format）解析消息。
  • 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 文件中消息内定义的每个字段生成了一组访问器方法。这些方法采用小写/蛇形命名法（lower-case/snake-case），例如 has_foo() 和 clear_foo()。

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

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

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

显式存在（Explicit Presence）数值字段

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

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++ 类型。

隐式存在（Implicit Presence）数值字段

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

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++ 类型。

显式存在（Explicit Presence）字符串/字节字段

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

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

注意： 从 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];

cord 不可用于 repeated bytes 字段。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() 将返回 value 作为 absl::Cord。
  • void clear_foo()：清除字段的值。调用此方法后，foo() 将返回一个空的 Cord（proto3）或默认值（proto2 和 editions）。
  • bool has_foo()：如果字段已设置，则返回 true。仅适用于 proto3 中的 optional 字段和 editions 中的显式存在字段。

显式存在（Explicit Presence）枚举字段

给定枚举类型：

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

隐式存在（Implicit Presence）枚举字段

给定枚举类型：

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

显式存在（Explicit Presence）嵌入消息字段

给定消息类型：

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）数值字段

对于此字段定义：

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++ 类型。

重复（Repeated）字符串字段

注意： 从 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 的迭代器和其他方法。

重复（Repeated）枚举字段

给定枚举类型：

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 的情况是 kFoo，则返回 true。
  • int32 foo() const：如果 oneof 的情况是 kFoo，则返回字段的当前值。否则，返回默认值。
  • void set_foo(int32 value):
    • 如果同一个 oneof 中的任何其他字段已设置，则调用 clear_example_name()。
    • 设置此字段的值并将 oneof 的情况设置为 kFoo。
    • has_foo() 将返回 true，foo() 将返回 value，并且 example_name_case() 将返回 kFoo。
  • void clear_foo():
    • 如果 oneof 的情况不是 kFoo，则不作任何更改。
    • 如果 oneof 的情况是 kFoo，则清除字段的值和 oneof 的情况。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 的情况是 kFoo，则返回 true。
  • const string& foo() const：如果 oneof 的情况是 kFoo，则返回字段的当前值。否则，返回默认值。
  • void set_foo(::absl::string_view value):
    • 如果同一个 oneof 中的任何其他字段已设置，则调用 clear_example_name()。
    • 设置此字段的值并将 oneof 的情况设置为 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 的情况设置为 kFoo，并返回一个指向存储字段值的可变字符串对象的指针。如果在调用之前 oneof 的情况不是 kFoo，则返回的字符串将为空（不是默认值）。
    • has_foo() 将返回 true，foo() 将返回写入给定字符串的任何值，example_name_case() 将返回 kFoo。
  • void clear_foo():
    • 如果 oneof 的情况不是 kFoo，则不作任何更改。
    • 如果 oneof 的情况是 kFoo，则释放字段并清除 oneof 的情况。has_foo() 将返回 false，foo() 将返回默认值，example_name_case() 将返回 EXAMPLE_NAME_NOT_SET。
  • void set_allocated_foo(string* value):
    • 调用 clear_example_name()。
    • 如果字符串指针不为 NULL：将字符串对象设置到字段，并将 oneof 的情况设置为 kFoo。消息将获得已分配字符串对象的所有权，has_foo() 将返回 true，example_name_case() 将返回 kFoo。
    • 如果字符串指针为 NULL，has_foo() 将返回 false，example_name_case() 将返回 EXAMPLE_NAME_NOT_SET。
  • string* release_foo():
    • 如果 oneof 的情况不是 kFoo，则返回 NULL。
    • 清除 oneof 的情况，释放字段的所有权，并返回字符串对象的指针。调用此方法后，调用者将获得已分配字符串对象的所有权，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 的情况是 kBar，则返回 true。
  • Bar bar() const：如果 oneof 的情况是 kBar，则返回字段的当前值。否则，返回默认值。
  • void set_bar(Bar value):
    • 如果同一个 oneof 中的任何其他字段已设置，则调用 clear_example_name()。
    • 设置此字段的值并将 oneof 的情况设置为 kBar。
    • has_bar() 将返回 true，bar() 将返回 value，并且 example_name_case() 将返回 kBar。
    • 在调试模式下（即 NDEBUG 未定义），如果 value 不匹配为 Bar 定义的任何值且它是一个封闭枚举，此方法将中止进程。
  • void clear_bar():
    • 如果 oneof 的情况不是 kBar，则不作任何更改。
    • 如果 oneof 的情况是 kBar，则清除字段的值和 oneof 的情况。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 的情况是 kBar，则返回 true。
  • const Bar& bar() const：如果 oneof 的情况是 kBar，则返回字段的当前值。否则，返回一个未设置任何字段的 Bar（可能是 Bar::default_instance()）。
  • Bar* mutable_bar():
    • 如果同一个 oneof 中的任何其他字段已设置，则调用 clear_example_name()。
    • 将 oneof 的情况设置为 kBar，并返回一个指向存储字段值的可变 Bar 对象的指针。如果在调用之前 oneof 的情况不是 kBar，则返回的 Bar 将没有任何字段被设置（即它将与一个新分配的 Bar 相同）。
    • 调用此方法后，has_bar() 将返回 true，bar() 将返回对同一个 Bar 实例的引用，并且 example_name_case() 将返回 kBar。
  • void clear_bar():
    • 如果 oneof 的情况不是 kBar，则不作任何更改。
    • 如果 oneof 的情况等于 kBar，则释放字段并清除 oneof 的情况。has_bar() 将返回 false，bar() 将返回默认值，并且 example_name_case() 将返回 EXAMPLE_NAME_NOT_SET。
  • void set_allocated_bar(Bar* bar):
    • 调用 clear_example_name()。
    • 如果 Bar 指针不为 NULL：将 Bar 对象设置到字段，并将 oneof 的情况设置为 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 的情况不是 kBar，则返回 NULL。
    • 如果 oneof 的情况是 kBar，则清除 oneof 的情况，释放字段的所有权，并返回 Bar 对象的指针。调用此方法后，调用者将获得已分配 Bar 对象的所有权，has_bar() 将返回 false，bar() 将返回默认值，并且 example_name_case() 将返回 EXAMPLE_NAME_NOT_SET。

映射字段

对于此 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，可以通过以下方式将其转换为标准 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 条目消息被放入包含该 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 的情况设置为 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 语句如果没有 default 分支，将无法捕获所有情况，即使列出了所有已知字段。这可能导致意外行为，包括数据损坏和运行时崩溃。请始终添加一个 default 分支或在 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()：返回该类型的描述符，其中包含有关此服务有哪些方法以及它们的输入和输出类型是什么的信息。

存根

protocol buffer 编译器还会为每个服务接口生成一个“存根”（stub）实现，供希望向实现该服务的服务器发送请求的客户端使用。对于 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 中可能会改变。