文章目录

Protobuf

Protobuf

1.定义消息

syntax = "proto3";

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 result_per_page = 3;
}

1.1 syntax

syntax指定您使用的是proto3语法：如果您不这样做，协议缓冲区编译器将假定您使用的是proto2。这必须是文件的第一个非空、非注释行。

1.2 分配标识号

每个字段后面都有一个唯一的数字，这个就是标识号。这些标识号是用来在message的二进制格式中识别各个字段的，一旦开始使用就不能够再改变，每个message内唯一即可，不同的message定义可以拥有相同的标识号。

注意：[1,15]之内的标识号在编码的时候会占用1个字节。[16,2047]之内的标识号占用2个字节。所以应该为那些频繁出现的消息元素保留 [1,15]之内的标识号。切记：要为将来有可能添加的、频繁出现的字段预留一些标识号。

1.3 保留标识号（Reserved）

如果你想保留一些标识号，留给以后用，可以使用下面语法：

message Foo {
  reserved 2, 15, 9 to 11; // 保留2，15，9到11这些标识号
}

如果使用了这些保留的标识号，protocol buffer编译器会输出警告信息。

1.4 注释

单行注释：//
多行注释：/**/

1.5 为消息定义包

例子：

package foo.bar;
message Open { ... }

1.6 关键字

关键字	说明
required	必须字段
optional	可选字段
repeated	表示该字段可以包含0~N个元素。其特性和optional一样，但是每一次可以包含多个值。可以看作是在传递一个数组的值。

2.数据类型

.proto Type	Notes	C# Type
double		double
float		float
bool		bool
string	必须是UTF-8编码或者7-bit ASCII编码的文本	string
int32	使用变长编码,编码负数的效率很低——如果字段可能有负数，请使用sint32。	int
sint32	使用变长编码，这些编码在负值时比int32高效的多	int
uint32	使用变长编码，无符号整数，无法表示负数	unit
int64	同int32	long
sint64	同int32	long
uint64	同int32	ulong
fixed32	总是四个字节。如果值经常大于2^32-4，则比uint32更有效	uint
fixed64	总是8个字节。如果值经常大于2^64-8时，比uint64高效。	ulong
sfixed32	总是4个字节	int
sfixed64	总是8个字节	long
byte	可以包含任意的字节序列。	ByteString

3.枚举

syntax = "proto3";//指定版本信息，不指定会报错

enum PhoneType //枚举消息类型，使用enum关键词定义,一个电话类型的枚举类型
{
    //option allow_alias = true;  成员拥有相同的值应该加上这句
    //reserved 2, 15, 9 to 11;    也可声明保留类型

    MOBILE = 0; //proto3版本中，首成员必须为0
    HOME = 1;
    WORK = 2;
}

// 定义一个电话消息
message PhoneNumber
{
    string number = 1; // 电话号码字段
    PhoneType type = 2; // 电话类型字段，电话类型使用PhoneType枚举类型
}

4.数组类型

在字段前面增加repeated关键词实现，标记当前字段是一个数组

message Msg {
  // 整数数组
  repeated int32 nums = 1;
  // string 数组
  repeated string names = 2;
}

5.map(字典)类型

key_type可以是任何整数或字符串类型（除浮点类型和字节之外的任何标量类型）。请注意，枚举不是有效的key_type。
value_type 可以是除另一个映射之外的任何类型。
map 字段不能使用repeated关键字修饰。

message Product
{
    string name = 1; // 商品名
    // 定义一个k/v类型，key是string类型，value也是string类型
    map<string, string> attrs = 2; // 商品属性，键值对
}

6.消息(自定义类)嵌套

6.1 引用其他消息类型的用法

// 定义Result消息
message Result {
  string url = 1;
  string title = 2;
  repeated string snippets = 3; // 字符串数组类型
}

// 定义SearchResponse消息
message SearchResponse {
  // 引用上面定义的Result消息类型，作为results字段的类型
  repeated Result results = 1; // repeated关键词标记，说明results字段是一个数组
}

6.2 消息嵌套

message SearchResponse {
  // 嵌套消息定义
  message Result {
    string url = 1;
    string title = 2;
    repeated string snippets = 3;
  }
  // 引用嵌套的消息定义
  repeated Result results = 1;
}

6.3 import导入其他proto文件定义的消息

syntax = "proto3";
// Result消息定义
message Result {
 string url = 1;
 string title = 2;
 repeated string snippets = 3; // 字符串数组类型
}

syntax = "proto3";
// 导入Result消息定义
import "result.proto";

// 定义SearchResponse消息
message SearchResponse {
 // 使用导入的Result消息
 repeated Result results = 1; 
}

Protobuf 协议