C++ 生成代码指南

精确描述 protocol buffer 编译器为任何给定 protocol 定义生成的 C++ 代码。

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

编译器调用

使用 --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；这些目录必须已经存在。

包

如果 .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*。

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

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

  • 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。

字段

除了上一节描述的方法之外，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 继承的任何方法，或者通过其他方式访问消息（例如，使用复制构造函数复制消息）。相应地，返回指针的值永远不能保证在两次不同的访问器调用之间相同。

可选数字字段 (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)

注意：截至 edition 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 风格的以 null 结尾的字符串设置字段的值。调用此方法后，has_foo() 将返回 true，foo() 将返回 value 的副本。
  • void set_foo(const char* value, int size)：使用指定了显式大小而不是通过查找 null 终止符字节确定的字符串设置字段的值。调用此方法后，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)

注意：截至 edition 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 风格的以 null 结尾的字符串设置字段的值。调用此方法后，foo() 将返回 value 的副本。
  • void set_foo(const char* value, int size)：使用指定了显式大小而不是通过查找 null 终止符字节确定的字符串设置字段的值。调用此方法后，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 添加了对absl::Cord 的支持，用于单数字节字段（包括oneof 字段）。单数字符串、重复字符串和重复字节字段不支持使用 Cord。

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

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

cord 不适用于重复字节字段。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++ 类型。

重复字符串字段

注意：截至 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)：使用指定了显式大小而不是通过查找 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 中的任何其他 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 字符串字段

注意：截至 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 中的任何其他 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 中的任何其他 oneof 字段，则调用 clear_example_name()。
    • 将 oneof case 设置为 kFoo 并返回存储字段值的可变 string 对象的指针。如果在调用之前 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()。
    • 如果 string 指针不为 NULL：将 string 对象设置到字段中并将 oneof case 设置为 kFoo。消息将拥有分配的 string 对象的所有权，has_foo() 将返回 true，并且 example_name_case() 将返回 kFoo。
    • 如果 string 指针为 NULL，has_foo() 将返回 false，并且 example_name_case() 将返回 EXAMPLE_NAME_NOT_SET。
  • string* release_foo():
    • 如果 oneof case 不是 kFoo，则返回 NULL。
    • 清除 oneof case，释放字段的所有权并返回 string 对象的指针。调用此方法后，调用者将拥有分配的 string 对象的所有权，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 是 protocol buffer 中用于存储 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());

解析未知值

在 wire format 中，.proto map 等同于每个键/值对一个 map entry 消息，而 map 本身是 map entries 的重复字段。与普通消息类型一样，解析后的 map entry 消息可能包含未知字段：例如，在定义为 map<int32, string> 的 map 中，类型为 int64 的字段。

如果 map entry 消息的 wire format 中存在未知字段，它们将被丢弃。

如果 map entry 消息的 wire format 中存在未知的枚举值，它在 proto2 和 proto3 中的处理方式不同。在 proto2 中，整个 map entry 消息被放入包含消息的未知字段集中。在 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。

枚举

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

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

扩展 (仅 proto2)

给定一个包含扩展范围的消息

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 的更多信息。

服务

如果 .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：Include 指令。
  • namespace_scope：属于文件包/命名空间但不属于任何特定类的声明。出现在所有其他命名空间范围代码之后。
  • global_scope：属于顶级，在文件命名空间之外的声明。出现在文件的最末尾。
  • class_scope:TYPENAME：属于消息类的成员声明。TYPENAME 是完整的 proto 名称，例如 package.MessageType。出现在类中所有其他公共声明之后。此插入点仅出现在 .pb.h 文件中。

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