ProtoBuf 语法（一）

待我称王封你为后i 2023-10-10 19:56 25阅读 0赞

`系列文章`  
[ProtoBuf 语法（二）][ProtoBuf]  
[ProtoBuf 语法（三）][ProtoBuf 1]

--------------------

### 文章目录 ###

*  前言
 *  一、字段规则
 *  二、消息类型的定义与使用
 *   *  2.1 定义
     *  2.2 使用
 *  三、enum 类型
 *   *  3.1 定义规则
     *  3.2 注意事项
 *  四、any 类型
 *   *  4.1 类型说明
     *  4.2 类型使用
 *  五、oneof 类型
 *  六、map 类型
 *  七、默认值

# 前言 #

前面的文章介绍了 ProtoBuf 的基本概念，同时也展示了其基本使用方法，本文将详细的介绍 ProtoBuf 更多的字段以及语法。

# 一、字段规则 #

消息的字段可以用下面几种规则来修饰：

*  singular：消息中可以包含该字段零次或⼀次（不超过⼀次）。在 proto3 语法中，定义的字段默认使用该规则。
 *  repeated：消息中可以包含该字段任意多次（包括零次），其中重复值的顺序会被保留。可以理解为定义了⼀个数组。

> 例如，更新 `contacts.proto`文件， `PeopleInfo` 消息中新增 `phone`字段，表示一个联系人有多个号码，可将其设置为 `repeated`，写法如下：

syntax = "proto3";
    package contacts;
    message PeopleInfo {
        
    	string name = 1;
    	int32 age = 2;
    	repeated string phone = 3;
    }

# 二、消息类型的定义与使用 #

## 2.1 定义 ##

在单个`.proto`文件中可以定义多个消息体，且支持定义嵌套类型的消息（任意多层）。每个消息体中的字段编号可以重复。

> 例如，更新`contacts.proto`文件，可以将`phone`提取出来，单独成为⼀个消息：

// -------------------------- 嵌套写法 -------------------------
    syntax = "proto3";
    package contacts;
    message PeopleInfo {
        
    	string name = 1;
    	int32 age = 2;
    	message Phone {
        
    		string number = 1;
    	}
    }
    
    // -------------------------- ⾮嵌套写法 -------------------------
    syntax = "proto3";
    package contacts;
    message Phone {
        
    	string number = 1;
    }
    message PeopleInfo {
        
    	string name = 1;
    	int32 age = 2;
    }

## 2.2 使用 ##

**消息类型可作为字段类型使用：**

> `contacts.proto`文件：

syntax = "proto3";
    package contacts;
    // 联系⼈
    message PeopleInfo {
        
    	string name = 1;
    	int32 age = 2;
    	message Phone {
        
    		string number = 1;
    	}
    	repeated Phone phone = 3;
    }

**可导入其他`.proto`文件的消息并使用：**

> 例如`Phone`消息定义在`phone.proto`文件中：

syntax = "proto3";
    package phone;
    message Phone {
        
    	string number = 1;
    }

**`contacts.proto`中的`PeopleInfo` 使用`Phone` 消息：**

syntax = "proto3";
    package contacts;
    import "phone.proto"; // 使⽤ import 将 phone.proto ⽂件导⼊进来 !!!
    message PeopleInfo {
        
    	string name = 1;
    	int32 age = 2;
    	// 引⼊的⽂件声明了package，使⽤消息时，需要⽤ ‘命名空间.消息类型’ 格式
    	repeated phone.Phone phone = 3;
    }

# 三、enum 类型 #

## 3.1 定义规则 ##

`proto3`语法支持我们自己定义枚举类型，枚举类型在`.proto`文件中的编写规范如下：

*  枚举类型名称：使用驼峰命名法，首字母大写。例如：`MyEnum`
 *  常量值名称：全大写字母，多个字母之间使用`_`连接，例如：`ENUM_CONST = 0;`

> 例如，定义一个名为`PhoneType`的枚举类型：

enum PhoneType {
        
    	MP = 0; // 移动电话
    	TEL = 1; // 固定电话
    }

**需要注意枚举类型的定义有以下规则：**

1.  0 值常量必须存在，且必须作为第一个元素。这是为了与`proto2`的语法兼容：第一个元素作为默认值，且值为 0。
2.  枚举类型可以定义在消息外，也可嵌套定义在消息之内。
3.  枚举的常量值在 32 位整数的范围内。但因负值无效因而不建议使用（与编码规则有关）。

## 3.2 注意事项 ##

将两个 `具有相同枚举值名称` 的枚举类型放在单个`.proto?`文件下测试时，编译后会报错：某某某常量已经被定义！所以这里要注意：

*  同级（同层）的枚举类型，各个枚举类型中的常量不能重名。
 *  单个`.proto`文件下，最外层枚举类型和嵌套枚举类型，不算同级。
 *  多个`.proto`文件下，若⼀个文件引入了其他文件，且每个文件都**未声明** `package`，每个`.proto`文件中的枚举类型都在最外层，也算同级。
 *  多个`.proto`文件下，若⼀个文件引入了其他文件，且每个文件**都声明了**`package`，不算同级。

> 例如下面枚举的定义：

// ---------------------- 情况1：同级枚举类型包含相同枚举值名称--------------------
    enum PhoneType {
        
    	MP = 0; // 移动电话
    	TEL = 1; // 固定电话
    }
    enum PhoneTypeCopy {
        
    	MP = 0; // 移动电话 // 编译后报错：MP 已经定义
    }
    
    // ---------------------- 情况2：不同级枚举类型包含相同枚举值名称-------------------
    enum PhoneTypeCopy {
        
    	MP = 0; // 移动电话 // ⽤法正确
    }
    message Phone {
        
    	string number = 1; // 电话号码
    	enum PhoneType {
        
    		MP = 0; // 移动电话
    		TEL = 1; // 固定电话
    	}
    }
    
    // ---------------------- 情况3：多⽂件下都未声明package--------------------
    // phone1.proto
    import "phone1.proto"
    enum PhoneType {
        
    	MP = 0; // 移动电话 // 编译后报错：MP 已经定义
    	TEL = 1; // 固定电话
    }
    // phone2.proto
    enum PhoneTypeCopy {
        
    	MP = 0; // 移动电话
    }
    
    // ---------------------- 情况4：多⽂件下都声明了package--------------------
    // phone1.proto
    import "phone1.proto"
    package phone1;
    enum PhoneType {
        
    	MP = 0; // 移动电话 // ⽤法正确
    	TEL = 1; // 固定电话
    }
    // phone2.proto
    package phone2;
    enum PhoneTypeCopy {
        
    	MP = 0; // 移动电话
    }

上面4种情况，分别对应了以上的四个注意事项。

# 四、any 类型 #

## 4.1 类型说明 ##

*  在`proto3`语法中，字段还可以声明为`Any`类型，可以理解为泛型类型。使用时可以在`Any`中存储任意消息类型。`Any`类型的字段也用`repeated`来修饰。

`Any`类型是`google`已经帮我们定义好的类型，在安装`ProtoBuf`时，其中的`include`目录下查找所有`google`已经定义好的`.proto`文件。

> 最初安装ProtoBuf的时候，我是将其安装到`\usr\local`目录下的，因此在该目录下查看即可：

![b318af50e0294977a37603d1aa419ace.png][]

## 4.2 类型使用 ##

例如，在我们的`contacts.proto`中，为联系人增加一个地址信息，就可以使用`Any`类型的字段来存储地址信息，更新`contacts.proto`文件内容如下：

**编译后，`contacts.pb.h`更新的部分代码展示：**

> 新生成的 `Address` 类：

class Address final : public ::PROTOBUF_NAMESPACE_ID::Message {
        
    public:
    	using ::PROTOBUF_NAMESPACE_ID::Message::CopyFrom;
    	void CopyFrom(const Address& from);
    	using ::PROTOBUF_NAMESPACE_ID::Message::MergeFrom;
    	void MergeFrom( const Address& from) {
        
    	Address::MergeImpl(*this, from);
    }
    // string home_address = 1;
    void clear_home_address();
    const std::string& home_address() const;
    template <typename ArgT0 = const std::string&, typename... ArgT>
    void set_home_address(ArgT0&& arg0, ArgT... args);
    std::string* mutable_home_address();
    PROTOBUF_NODISCARD std::string* release_home_address();
    void set_allocated_home_address(std::string* home_address);
    
    // string unit_address = 2;
    void clear_unit_address();
    const std::string& unit_address() const;
    template <typename ArgT0 = const std::string&, typename... ArgT>
    void set_unit_address(ArgT0&& arg0, ArgT... args);
    std::string* mutable_unit_address();
    PROTOBUF_NODISCARD std::string* release_unit_address();
    void set_allocated_unit_address(std::string* unit_address);
    };

> 更新的 `PeopleInfo` 类：

class PeopleInfo final : public ::PROTOBUF_NAMESPACE_ID::Message 
    {
        
    public:
    	// .google.protobuf.Any data = 4;
    	bool has_data() const;
    	void clear_data();
    	const ::PROTOBUF_NAMESPACE_ID::Any& data() const;
    	PROTOBUF_NODISCARD ::PROTOBUF_NAMESPACE_ID::Any* release_data();
    	::PROTOBUF_NAMESPACE_ID::Any* mutable_data();
    	void set_allocated_data(::PROTOBUF_NAMESPACE_ID::Any* data);
    };

上述的代码中，对于`Any`类型字段：

*  设置：设置方法可以使用`mutable_name`方法，返回值为`Any`类型的指针，这类方法会为我们开辟好空间，可以直接对这块空间的内容进行修改。
 *  获取：获取方法的方法名称与小写字段名称完全相同。

上面提到过，可以在`Any`字段中存储任意消息类型，这就要涉及到`任意消息类型`和 `Any`类型的互相转化。这部分代码就在`Google`为我们写好的头文件`any.pb.h` 中。`any.pb.h` 的部分代码展示如下：

class PROTOBUF_EXPORT Any final : public ::PROTOBUF_NAMESPACE_ID::Message 
    {
        
    	bool PackFrom(const ::PROTOBUF_NAMESPACE_ID::Message& message) {
        
    		//...
    	}
    	bool UnpackTo(::PROTOBUF_NAMESPACE_ID::Message* message) const {
        
    		//...
    	}
    	template<typename T> bool Is() const {
        
    		return _impl_._any_metadata_.Is<T>();
    	}
    };

**说明：**

*  使用 `PackFrom()` 方法可以将任意消息类型转为 `Any` 类型。
 *  使用 `UnpackTo()` 方法可以将 `Any` 类型转回之前设置的任意消息类型。
 *  使用 `Is()` 方法可以用来判断存放的消息类型是否为 `typename T`。

# 五、oneof 类型 #

如果消息中有很多可选字段，并且将来同时只有⼀个字段会被设置，那么就可以使用 `oneof` 字段来加强这个行为，也能有节约内存的效果。`oneof` 字段定义的格式为：`oneof 字段名 { 字段1; 字段2; ... }` 。

例如在`contacts.protp`文件中为联系人新增其他的联系方式，比如QQ或者微信二选一。这里就可以使用到`oneof`字段来实现这个多选一的行为。

**更新`contacts.proto`文件内容如下：**

// 首行：语法指定
    syntax = "proto3";
    package contacts2; //指定作用域
    
    import "google/protobuf/any.proto";
    
    message Address
    {
        
        string home_address = 1; //家庭住址
        string unit_address = 2; //单位地址
    }
    
    message PeopleInfo 
    {
        
        string name = 1; //姓名
        int32 age = 2;   //年龄
        // repeated string phone_numbers = 3;
    
        // 嵌套定义message
        message Phone 
        {
        
            string number = 1;
    
            //使用枚举，增加电话类型
            enum PhoneType
            {
        
                MP = 0;  //移动电话
                TEL = 1; //固定电话
            }
    
            PhoneType type = 2;
        }
    
        repeated Phone phone = 3; //电话信息
    
        google.protobuf.Any data = 4; //Any 类型存储地址
    
        // 如果消息中有很多可选字段，并且将来同时只有⼀个字段会被设置，那么就可以使⽤ oneof 字段来加强这个⾏为，也能有节约内存的效果。
        oneof other_contact //其他联系方式，多种只存在其一，如果都设置了，只保留最后一次设置的字段
        {
        
            // repeated string qq = 5; //不能使用 repeated
            string qq = 5;
            string wexing = 6;
        }
    }
    
    //通讯录message
    message Contacts 
    {
        
        repeated PeopleInfo contacts = 1; 
    }

**注意事项：**

*  可选字段的编号不能与其他非可选字段的编号冲突。
 *  不能在`oneof`字段中使用`repeated`字段。
 *  将来在设置`oneof`字段中的值时，如果将`oneof`中的字段设置了多个，那么只会保留最后一次设置的成员，之前设置的`oneof`成员会自动清除。

**编译后，`contacts.pb.h`更新的部分代码展示：**

> 更新的 `PeopleInfo` 类:

class PeopleInfo final : public ::PROTOBUF_NAMESPACE_ID::Message {
        
    	enum OtherContactCase {
        
    		kQq = 5,
    		kWeixin = 6,
    		OTHER_CONTACT_NOT_SET = 0,
    	};
    	
    	// string qq = 5;
    	bool has_qq() const;
    	void clear_qq();
    	const std::string& qq() const;
    	template <typename ArgT0 = const std::string&, typename... ArgT>
    	void set_qq(ArgT0&& arg0, ArgT... args);
    	std::string* mutable_qq();
    	PROTOBUF_NODISCARD std::string* release_qq();
    	void set_allocated_qq(std::string* qq);
    	
    	// string weixin = 6;
    	bool has_weixin() const;
    	void clear_weixin();
    	const std::string& weixin() const;
    	template <typename ArgT0 = const std::string&, typename... ArgT>
    	void set_weixin(ArgT0&& arg0, ArgT... args);
    	std::string* mutable_weixin();
    	PROTOBUF_NODISCARD std::string* release_weixin();
    	void set_allocated_weixin(std::string* weixin);
    	void clear_other_contact();
    	OtherContactCase other_contact_case() const;
    };

上述的代码中，对于`oneof`字段有以下几点需要注意：

*  将`oneof`中的多个字段定义为⼀个枚举类型。
 *  设置和获取：对`oneof`内的字段进行常规的设置和获取即可，但要注意只能设置⼀个。如果设置多个，那么只会保留最后一次设置的成员。
 *  清空`oneof`字段：`clear_name`方法。

# 六、map 类型 #

在`proto3`语法中，支持创建⼀个关联映射的字段，也就是可以使用`map`类型去声明字段类型，格式为：

> `map<key_type, value_type> map_field = N;`

**注意事项：**

*  `key_type` 是除了`float`和`bytes`类型以外的任意标量类型。`value_type` 可以是任意类型。
 *  `map` 字段不可以用`repeated`修饰。
 *  `map`中存入的元素是无序的。

例如在`contacts.protp`文件中为联系人新增备注信息。这里就可以使用到`map`类型的字段来存储备注信息。更新`contacts.proto`文件内容如下：

// 首行：语法指定
    syntax = "proto3";
    package contacts2; //指定作用域
    
    import "google/protobuf/any.proto";
    
    message Address
    {
        
        string home_address = 1; //家庭住址
        string unit_address = 2; //单位地址
    }
    
    message PeopleInfo 
    {
        
        string name = 1; //姓名
        int32 age = 2;   //年龄
        // repeated string phone_numbers = 3;
    
        // 嵌套定义message
        message Phone 
        {
        
            string number = 1;
    
            //使用枚举，增加电话类型
            enum PhoneType
            {
        
                MP = 0;  //移动电话
                TEL = 1; //固定电话
            }
    
            PhoneType type = 2;
        }
    
        repeated Phone phone = 3; //电话信息
    
        google.protobuf.Any data = 4; //Any 类型存储地址
    
        // 如果消息中有很多可选字段，并且将来同时只有⼀个字段会被设置，那么就可以使⽤ oneof 字段来加强这个⾏为，也能有节约内存的效果。
        oneof other_contact //其他联系方式，多种只存在其一，如果都设置了，只保留最后一次设置的字段
        {
        
            // repeated string qq = 5; //不能使用 repeated
            string qq = 5;
            string wechat = 6;
        }
    
        // 使用 map ⽀持创建⼀个关联映射字段，也就是可以使⽤?map?类型去声明字段类型，格式为：map<key_type, value_type> map_field = N;
        // key_type 是除了 float 和 bytes 类型以外的任意标量类型。 value_type 可以是任意类型。
        // map 字段不可以⽤ repeated 修饰
        // map 中存⼊的元素是⽆序的
        map<string, string> remark = 7; //备注信息
    }
    
    //通讯录message
    message Contacts 
    {
        
        repeated PeopleInfo contacts = 1; 
    }

**编译后，`contacts.pb.h`更新的部分代码展示：**

> 更新的 `PeopleInfo` 类:

class PeopleInfo final : public ::PROTOBUF_NAMESPACE_ID::Message {
        
    	// map<string, string> remark = 7;
    	int remark_size() const;
    	void clear_remark();
    	const ::PROTOBUF_NAMESPACE_ID::Map< std::string, std::string >&
    	remark() const;
    	::PROTOBUF_NAMESPACE_ID::Map< std::string, std::string >*
    	mutable_remark();
    };

**上述的代码中，对于`Map`类型的字段说明：**

*  清空`Map`：`clear_`方法。
 *  设置：设置方法为`mutable_name`方法，返回值为`Map`类型的指针，这类方法会为我们开辟好空间，可以直接对这块空间的内容进行修改。
 *  获取：获取方法的方法名称与小写字段名称完全相同。

# 七、默认值 #

反序列化消息时，如果被反序列化的二进制序列中不包含某个字段，反序列化对象中相应字段时，就会设置为该字段的默认值。不同的类型对应的默认值不同，以下是常见类型对应的默认值：

<table> 
 <thead> 
  <tr> 
   <th>类型</th> 
   <th>默认值</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>string</td> 
   <td>空字符串</td> 
  </tr> 
  <tr> 
   <td>bytes</td> 
   <td>空字节</td> 
  </tr> 
  <tr> 
   <td>bool</td> 
   <td>false</td> 
  </tr> 
  <tr> 
   <td>数值类型</td> 
   <td>0</td> 
  </tr> 
  <tr> 
   <td>enum</td> 
   <td>默认值的第⼀个定义的枚举值为 0</td> 
  </tr> 
  <tr> 
   <td>repeated</td> 
   <td>默认为空</td> 
  </tr> 
  <tr> 
   <td>信息字段</td> 
   <td>未设置该字段，它的取值依赖所要编译的语⾔</td> 
  </tr> 
 </tbody> 
</table>

另外，对于 `消息字段` 、 `oneof`字段和`any`字段 ，C++ 和 Java 语言中都有`has_`方法来检测当前字段是否被设置。

[ProtoBuf]: http://t.csdn.cn/oEcz6
[ProtoBuf 1]: http://t.csdn.cn/NoxRG
[b318af50e0294977a37603d1aa419ace.png]: https://img-blog.csdnimg.cn/b318af50e0294977a37603d1aa419ace.png