操作流程
我们将要使用的示例是一个非常简单的 “地址簿” 应用程序，可以在文件中读写联系人的详细信息。地址簿中的每个人都有姓名、ID、电子邮件地址和联系电话。
要创建地址簿应用程序，你需要从 .proto 文件开始。.proto 文件中的定义很简单：为要序列化的每个数据结构添加 message 定义，然后为 message 中的每个字段指定名称和类型。
下面就是定义相关 message 的 .proto 文件，addressbook.proto。
消息由至少一个字段组合而成，类似于C语言中的结构体，每个字段都有一定的格式：
数据类型 字段名称 = 唯一的编号标签值;
//文件名：addressbook.proto
syntax = "proto2";//proto版本
//.proto文件新增一个可选的package声明符，用来防止不同的消息类型有命名冲突。
//包的声明符会根据使用语言的不同影响生成的代码。对于C++，产生的类会被包装在C++的命名空间中。
package tutorial;package声明符
message Person {
required string name = 1;//姓名，= 1 二进制编码中使用的唯一 “标记”
required int32 id = 2;//ID
optional string email = 3;//email
enum PhoneType {//枚举消息类型
MOBILE = 0;//proto3版本中，首成员必须为0，成员不应有相同的值
HOME = 1;
WORK = 2;
}
//
message PhoneNumber {
required string number = 1;
optional PhoneType type = 2 [default = HOME];
}
repeated PhoneNumber phones = 4;//phones为数组
}
message AddressBook {
repeated Person people = 1;
}
Person 包含 PhoneNumber message ， AddressBook 包含 Person message。你甚至可以定义嵌套在其他 message 中的 message 类型 - 如你所见，PhoneNumber 类型在 Person 中定义。
如果你希望其中一个字段具有预定义的值列表中的值，你还可以定义枚举类型 - 此处你指定（枚举）电话号码，它的值可以是 MOBILE，HOME 或 WORK 之一。
既然你已经有了一个 .proto 文件，那么你需要做的下一件事就是生成你需要读写AddressBook（以及 Person 和 PhoneNumber ） message 所需的类。
为此，你需要在 .proto 上运行 protocol buffer 编译器 protoc：
protoc addressbook.proto --cpp_out=./
通过protoc工具编译.proto文件时，编译器将生成所选择语言的代码，这些代码可以操作在.proto文件中定义的消息类型，包括获取、设置字段值，将消息序列化到一个输出流中，以及从一个输入流中解析消息。
对C++来说，编译器会为每个.proto文件生成一个.h文件和一个.cc文件，.proto文件中的每一个消息有一个对应的类。
编译器为你创建了哪些类和函数。如果你查看 addressbook.pb.h，你会发现你在 addressbook.proto 中指定的每条 message 都有一个对应的类。仔细观察 Person 类，你可以看到编译器已为每个字段生成了访问器。例如，对于 name ，id，email 和 phone 字段，你可以使用以下方法：
//setter 方法以 set_ 开头
// required name
inline bool has_name() const;//has_ 方法，如果设置了该字段，则返回 true
inline void clear_name();//clear_ 方法，可以将字段重新设置回 empty 状态
inline const ::std::string& name() const;
inline void set_name(const ::std::string& value);
inline void set_name(const char* value);
inline ::std::string* mutable_name();
// required id
inline bool has_id() const;//has_ 方法，如果设置了该字段，则返回 true
inline void clear_id();//clear_ 方法，可以将字段重新设置回 empty 状态
inline int32_t id() const;
inline void set_id(int32_t value);
// optional email
inline bool has_email() const;//has_ 方法，如果设置了该字段，则返回 true
inline void clear_email();//clear_ 方法，可以将字段重新设置回 empty 状态
inline const ::std::string& email() const;
inline void set_email(const ::std::string& value);
inline void set_email(const char* value);
inline ::std::string* mutable_email();
// repeated phones
inline int phones_size() const;//检查 repeated 字段长度（换句话说，与此人关联的电话号码数）
inline void clear_phones();
inline const ::google::protobuf::RepeatedPtrField< ::tutorial::Person_PhoneNumber >& phones() const;
inline ::google::protobuf::RepeatedPtrField< ::tutorial::Person_PhoneNumber >* mutable_phones();
inline const ::tutorial::Person_PhoneNumber& phones(int index) const;//使用索引获取指定的电话号码
inline ::tutorial::Person_PhoneNumber* mutable_phones(int index);//更新指定索引处的现有电话号码
inline ::tutorial::Person_PhoneNumber* add_phones();//在 message 中添加另一个电话号码同时之后也可进行再修改（repeated 的标量类型有一个 add_，而且只允许你传入新值）
每个 message 类还包含许多其他方法，可用于检查或操作整个 message，包括：
bool IsInitialized() const;: 检查是否已设置所有必填 required 字段string DebugString() const;: 返回 message 的人类可读表达，对调试特别有用void CopyFrom(const Person& from);用给定的 message 的值覆盖 messagevoid Clear();: 将所有元素清除回 empty 状态每个 protocol buffer 类都有使用 protocol buffer 二进制格式 读写所选类型 message 的方法。包括：
bool SerializeToString(string* output) const;:序列化消息并将字节存储在给定的字符串中。请注意，字节是二进制的，而不是文本;我们只使用 string 类作为方便的容器。bool ParseFromString(const string& data);: 解析给定字符串到 messagebool SerializeToOstream(ostream* output) const;: 将 message 写入给定的 C++的 ostreambool ParseFromIstream(istream* input);: 解析给定 C++ istream 到 message地址簿应用程序能够做的第一件事可能是将个人详细信息写入的地址簿文件。为此，你需要创建并填充 Protocol Buffer 类的实例，然后将它们写入输出流。
这是一个从文件中读取 AddressBook 的程序，根据用户输入向其添加一个新 Person，并将新的 AddressBook 重新写回文件。其中直接调用或引用 protocol 编译器生成的代码部分将高亮显示。
“直接调用或引用 protocol 编译器生成的代码部分” 采用注释 ＠＠＠ 的方式标出
#include <iostream>
#include <fstream>
#include <string>
#include "addressbook.pb.h"
using namespace std;
// This function fills in a Person message based on user input.
void PromptForAddress(tutorial::Person* person) {
cout << "Enter person ID number: ";
int id;
cin >> id;
person->set_id(id);//设置ID
cin.ignore(256, '\n');
cout << "Enter name: ";
getline(cin, *person->mutable_name());
cout << "Enter email address (blank for none): ";
string email;
getline(cin, email);
if (!email.empty()) {
person->set_email(email);//设置email
}
while (true) {
cout << "Enter a phone number (or leave blank to finish): ";
string number;
getline(cin, number);
if (number.empty()) {
break;
}
// ＠＠＠ Person::PhoneNumber
tutorial::Person::PhoneNumber* phone_number = person->add_phones();
phone_number->set_number(number);
cout << "Is this a mobile, home, or work phone? ";
string type;
getline(cin, type);//不同的枚举类型设置不同的参数
if (type == "mobile") {
// ＠＠＠ Person
phone_number->set_type(tutorial::Person::MOBILE);
} else if (type == "home") {
// ＠＠＠ Person
phone_number->set_type(tutorial::Person::HOME);
} else if (type == "work") {
// ＠＠＠ Person
phone_number->set_type(tutorial::Person::WORK);
} else {
cout << "Unknown phone type. Using default." << endl;
}
}
}
// Main function: Reads the entire address book from a file,
// adds one person based on user input, then writes it back out to the same
// file.
int main(int argc, char* argv[]) {
//验证你没有意外链接到与你编译的头文件不兼容的库版本。
//如果检测到版本不匹配，程序将中止。请注意，每个 .pb.cc 文件在启动时都会自动调用此宏。
GOOGLE_PROTOBUF_VERIFY_VERSION;
if (argc != 2) {
cerr << "Usage: " << argv[0] << " ADDRESS_BOOK_FILE" << endl;
return -1;
}
// ＠＠＠ AddressBook
tutorial::AddressBook address_book;
{
// Read the existing address book.
fstream input(argv[1], ios::in | ios::binary);
if (!input) {
cout << argv[1] << ": File not found. Creating a new file." << endl;
// ＠＠＠ ParseFromIstream
} else if (!address_book.ParseFromIstream(&input)) {//解析给定字符串到 input
cerr << "Failed to parse address book." << endl;
return -1;
}
}
// Add an address.
PromptForAddress(address_book.add_people());
{
// Write the new address book back to disk.
fstream output(argv[1], ios::out | ios::trunc | ios::binary);
// ＠＠＠ SerializeToOstream
if (!address_book.SerializeToOstream(&output)) {//将 message 写入给定的 C++ 的 ostream
cerr << "Failed to write address book." << endl;
return -1;
}
}
// Optional: Delete all global objects allocated by libprotobuf.
// ＠＠＠ ShutdownProtobufLibrary
google::protobuf::ShutdownProtobufLibrary();
return 0;
}
另请注意在程序结束时调用 ShutdownProtobufLibrary()。所有这一切都是删除 Protocol Buffer 库分配的所有全局对象。对于大多数程序来说这是不必要的，因为该过程无论如何都要退出，并且操作系统将负责回收其所有内存。但是，如果你使用了内存泄漏检查程序，该程序需要释放每个最后对象，或者你正在编写可以由单个进程多次加载和卸载的库，那么你可能希望强制使用 Protocol Buffers 来清理所有内容。
此示例读取上面示例创建的文件并打印其中的所有信息。
#include <iostream>
#include <fstream>
#include <string>
#include "addressbook.pb.h"
using namespace std;
// Iterates though all people in the AddressBook and prints info about them.
void ListPeople(const tutorial::AddressBook& address_book) {
for (int i = 0; i < address_book.people_size(); i++) {//proto设置为4
const tutorial::Person& person = address_book.people(i);
cout << "Person ID: " << person.id() << endl;
cout << " Name: " << person.name() << endl;
if (person.has_email()) {
cout << " E-mail address: " << person.email() << endl;
}
for (int j = 0; j < person.phones_size(); j++) {
const tutorial::Person::PhoneNumber& phone_number = person.phones(j);
switch (phone_number.type()) {
case tutorial::Person::MOBILE:
cout << " Mobile phone #: ";
break;
case tutorial::Person::HOME:
cout << " Home phone #: ";
break;
case tutorial::Person::WORK:
cout << " Work phone #: ";
break;
}
cout << phone_number.number() << endl;
}
}
}
// Main function: Reads the entire address book from a file and prints all
// the information inside.
int main(int argc, char* argv[]) {
// Verify that the version of the library that we linked against is
// compatible with the version of the headers we compiled against.
GOOGLE_PROTOBUF_VERIFY_VERSION;
if (argc != 2) {
cerr << "Usage: " << argv[0] << " ADDRESS_BOOK_FILE" << endl;
return -1;
}
tutorial::AddressBook address_book;
{
// Read the existing address book.
fstream input(argv[1], ios::in | ios::binary);
if (!address_book.ParseFromIstream(&input)) {
cerr << "Failed to parse address book." << endl;
return -1;
}
}
ListPeople(address_book);
// Optional: Delete all global objects allocated by libprotobuf.
google::protobuf::ShutdownProtobufLibrary();
return 0;
}
在发布使用 protocol buffer 的代码之后，无疑早晚有一天你将会想要 “改进” protocol buffer 的定义。如果你希望你的新 buffer 向后兼容，并且你的旧 buffer 是向前兼容的（实际上你一定想要这种兼容性） - 那么你需要遵循一些规则。在新版本的 protocol buffer 中：
如果你遵循这些规则，旧代码将很乐意阅读新消息并简单地忽略任何新字段。对于旧代码，已删除的可选字段将只具有其默认值，删除的重复字段将为空。新代码也将透明地读取旧消息。但是，请记住旧的 message 中不会出现新的可选字段，因此你需要明确通过调用 has_ 方法来检查它们是否被设置，或者在字段编号后面使用 [default = value] 在 .proto 文件中提供合理的默认值。如果未为 optional 元素指定默认值，则使用特定于类型的默认值：对于字符串，默认值为空字符串。对于布尔值，默认值为 false。对于数字类型，默认值为零。另请注意，如果添加了新的 repeated 字段，则新代码将无法判断它是否为空（通过新代码）或从未设置（通过旧代码），因为它没有 has_ 标志。
1、https://www.jianshu.com/p/d2bed3614259
2、https://blog.csdn.net/m0_46083365/article/details/103718080
3、https://blog.csdn.net/wobutianl/article/details/70241614
4、https://blog.csdn.net/tennysonsky/article/details/73810180