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);
}
6. 注意事项
- 字段编号：确保每个字段有唯一的编号，并避免使用保留编号。
- 可选和重复字段：默认情况下，字段是可选的。使用
repeated关键字定义数组或列表。 - 命名规范：使用驼峰命名法（
camelCase）命名字段，使用帕斯卡命名法（PascalCase）命名消息类型和服务名。 - 保持兼容性：如果需要对
.proto文件进行修改，尽量保持向后兼容。不要修改或删除已有的字段编号，可以添加新的字段编号。
