Protocol Buffers 协议 .proto 文件的编写指南及注意事项

Protocol Buffers（简称protobuf）是Google提供的一种数据序列化协议(轻便高效)

编写 .proto 文件是定义 gRPC 服务和消息结构等的关键步骤。以下是详细指南，包括编写 .proto 文件的基本语法和注意事项。

1. 基本语法

一个 .proto 文件通常包括以下部分：

语法声明：指定使用的 Protocol Buffers 语法版本。
包声明：定义包名，用于避免命名冲突。
消息类型：定义请求和响应的消息结构。
服务定义：定义 gRPC 服务及其方法。

2. 基本结构

以下是一个简单的 .proto 文件结构：

syntax = "proto3"; // 使用 Protocol Buffers 语法版本 3

package example; // 定义包名

// 定义请求消息类型
message HelloRequest {
  string name = 1; // 字段类型 字段名 = 字段编号;
}

// 定义响应消息类型
message HelloResponse {
  string message = 1;
}

// 定义 gRPC 服务
service Greeter {
  rpc SayHello (HelloRequest) returns (HelloResponse); // 方法名 (请求消息类型) 返回 (响应消息类型)
}

3. 字段类型

.proto 文件支持多种基本类型和复杂类型：

基本类型：
- double: 双精度浮点数
- float: 单精度浮点数
- int32: 32 位整数
- int64: 64 位整数
- uint32: 无符号 32 位整数
- uint64: 无符号 64 位整数
- sint32: 有符号 32 位整数
- sint64: 有符号 64 位整数
- fixed32: 固定长度 32 位整数
- fixed64: 固定长度 64 位整数
- sfixed32: 有符号固定长度 32 位整数
- sfixed64: 有符号固定长度 64 位整数
- bool: 布尔值
- string: 字符串
- bytes: 字节序列
复杂类型：
- message: 消息类型，用于嵌套结构
- enum: 枚举类型

4. 字段编号

字段编号用于唯一标识消息中的字段，取值范围是 1 到 2^29-1。避免使用 19000-19999 的编号，因为这些编号在 Protocol Buffers 中被保留用于未来扩展。

5. 示例

以下是一个更复杂的示例，包含嵌套消息和枚举类型：

syntax = "proto3";

package example;

// 嵌套消息类型
message Address {
  string street = 1;
  string city = 2;
  string state = 3;
  string zip = 4;
}

// 枚举类型
enum PhoneType {
  MOBILE = 0;
  HOME = 1;
  WORK = 2;
}

// 嵌套消息类型
message PhoneNumber {
  string number = 1;
  PhoneType type = 2;
}

// 定义联系人消息类型
message Contact {
  string name = 1;
  Address address = 2;
  repeated PhoneNumber phones = 3; // repeated 表示数组或列表
}

// 定义请求消息类型
message GetContactRequest {
  string id = 1;
}

// 定义响应消息类型
message GetContactResponse {
  Contact contact = 1;
}

// 定义 gRPC 服务
service ContactService {
  rpc GetContact (GetContactRequest) returns (GetContactResponse);
}