protobuf 语法介绍

基本语法

syntax = "proto3";

package test;

option go_package = "/test;test";

message RequestInfo {
  int64 number1 = 1;
  int64 number2 = 2;
}

1. syntax = "proto3"指定 proto3语法版本，默认为 proto2语法版本。
2. package test 设置包名。
3. option go_package = "/test;test" ;前设置的是生成 go文件的路径， ;后设置的是 go文件的包名。

定义消息

语法

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

1. message定义消息的关键字。
2. SearchRequest定义消息名称。
3. 大括号里面设置的是各个字段的类型、名称、标识号。
4. 标识号必须是唯一的。

枚举

// 枚举定义
enum Corpus {
  CORPUS_UNSPECIFIED = 0;
  CORPUS_UNIVERSAL = 1;
}

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 results_per_page = 3;
  Corpus corpus = 4; // 枚举使用
}

1. 使用 enum关键字定义。
2. proto3中枚举的第一个枚举值必须是0。

数组

// 定义用户消息类型
message User {
  string name = 1;
  int32 age = 2;
}
message SearchResponse {
  repeated User users = 1; // 返回用户数组
}

1. 使用 repeated关键字。
2. repeated标识该字段可以重复多次，用于表示数组。

map

语法：map<key_type, value_type> field_name = field_number。

1. key_type表示 map键的类型。
2. value_type标识 map值的类型。

// 定义用户消息类型
message User {
  string name = 1;
  int32 age = 2;
}
message SearchResponse {
  map<string, Contact> users = 1; // 定义map类型字段
}

默认值

• 对于字符串，默认值为空字符串。
• 对于字节，默认值为空字节。
• 对于布尔类型，默认值为 false。
• 对于数值类型，默认值为零。对于浮点型和双型， -0.0 和 0.0 被视为等效值，并将往返。
• 对于枚举，默认值是第一个定义的枚举值值，该值必须为 0。
• 对于消息字段，未设置该字段。它的确切值是取决于语言。

是否必须

1. optional表示该字段是可选的。
2. required表示该字段是必须的。

// 定义用户消息类型
message User {
  required name = 1; // 必须
  optional int32 age = 2; // 可选
}

其它类型

.proto Type	Notes	Go Type
double		float64
float		float32
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64
uint32	Uses variable-length encoding.	uint32
uint64	Uses variable-length encoding.	uint64
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 228.	uint32
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 256.	uint64
sfixed32	Always four bytes.	int32
sfixed64	Always eight bytes.	int64
bool		bool
string	A string must always contain UTF-8 encoded or 7-bit ASCII text, and cannot be longer than 232.	string
bytes	May contain any arbitrary sequence of bytes no longer than 232.	[]byte

定义服务

定义一个RPC服务的方法，它接受你的SearchRequest并返回一个SearchResponse。

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

message User {
  string name = 1;
  int32 age = 2;
}
message SearchResponse {
  repeated User users = 1; // 返回用户数组
}

service SearchService {
  rpc Search(SearchRequest) returns (SearchResponse);
}

1. service定义服务的关键字。
2. SearchService定义服务名称。
3. Search是方法名称。
4. SearchRequest是方法的参数。
5. SearchResponse是方法的返回值。

导入其它包

可以通过 *import*其他文件来使用这些文件中的定义。

import "other.proto";