3. Proto 文件定义：message、service、字段类型与标签、import 与 package

在 gRPC 微服务中，Proto 文件（.proto）是服务契约的核心。它定义了客户端与服务端之间通信的数据结构（message）和远程调用接口（service）。本章将系统讲解 Proto 文件的各个组成部分，包括字段类型、标签规则、包管理与导入机制，为后续编写流式接口打下坚实基础。

3.1 message 定义：数据结构的基本单元

message 用于定义结构化数据，类似于 Go 中的 struct。每个 message 包含若干字段，每个字段由 字段类型、字段名、字段编号（标签） 组成。

syntax = "proto3";

message User {
  int64  id       = 1;
  string name     = 2;
  string email    = 3;
  int32  age      = 4;
  bool   is_active = 5;
}

字段编号（Field Number）在 Proto3 中至关重要：

• 唯一性：每个字段在同一个 message 内必须拥有唯一的编号。
• 不可变：一旦发布使用，字段编号不应修改，否则会破坏向后兼容性。
• 范围：1 ~ 15 编号占用 1 字节，16 ~ 2047 占用 2 字节。高频字段应使用小编号以节省传输带宽。

3.2 字段类型与默认值

Proto3 支持多种标量类型，与 Go 类型的映射关系如下：

3.3 复合类型与嵌套 message

message 内部可以包含其他 message 类型，支持嵌套定义：

message Address {
  string street   = 1;
  string city     = 2;
  string zip_code = 3;
}

message User {
  int64   id              = 1;
  string  name            = 2;
  Address home_address    = 3;  // 引用其他 message
  repeated string tags    = 4;  // 重复字段，类似切片
  map<string, string> attributes = 5; // map 类型
}

• repeated：表示字段可以重复任意次数（包括 0），在 Go 中生成切片类型。
• map<K, V>：键值对映射，键类型必须是标量或 string。
• 嵌套 message：支持在一个 message 内部定义另一个 message，作用域仅限于父 message。

3.4 service 定义：接口契约

service 关键字定义 RPC 服务接口，包含一个或多个 RPC 方法。每个方法指定输入 message 和输出 message。

service UserService {
  // 一元 RPC：客户端发送一个请求，服务端返回一个响应
  rpc GetUser (GetUserRequest) returns (GetUserResponse);

  // 服务端流式 RPC：客户端发送一个请求，服务端返回流式响应
  rpc ListUsers (ListUsersRequest) returns (stream User);

  // 客户端流式 RPC：客户端发送流式请求，服务端返回一个响应
  rpc CreateUsers (stream CreateUserRequest) returns (CreateUsersResponse);

  // 双向流式 RPC：双方都可以发送和接收流式数据
  rpc Chat (stream ChatMessage) returns (stream ChatMessage);
}

流式接口的关键字 stream 放在 returns 或 参数 前面，表示该方向的数据是流式的。在 Go 生成的代码中，流式方法会返回一个特殊的流对象，支持 Send()、Recv() 操作。

3.5 package 与 import：模块化管理

package 用于避免命名冲突，类似于 Go 中的包名。在 Proto 文件中声明 package 后，生成的 Go 代码会对应到相应的包路径。

syntax = "proto3";

package user.v1;  // 声明包名

option go_package = "github.com/example/proto/gen/go/user/v1;userv1";

message User {
  int64  id   = 1;
  string name = 2;
}

• package：Proto 文件内的逻辑包名，用于避免 message 和 service 命名冲突。
• option go_package：指定生成的 Go 代码的导入路径和包名。格式为 导入路径;包名。

import 允许一个 Proto 文件引用另一个 Proto 文件中定义的 message 或 service：

// common.proto
syntax = "proto3";
package common.v1;
option go_package = "github.com/example/proto/gen/go/common/v1;commonv1";

message Timestamp {
  int64 seconds = 1;
  int32 nanos   = 2;
}

// user.proto 引用 common.proto
syntax = "proto3";
package user.v1;
option go_package = "github.com/example/proto/gen/go/user/v1;userv1";

import "common.proto";  // 导入其他 proto 文件

message User {
  int64  id              = 1;
  string name            = 2;
  common.v1.Timestamp created_at = 3;  // 使用导入的 message
}

3.6 字段标签（Field Number）的兼容性规则

字段标签是 Proto 文件向后兼容的核心机制。以下规则必须遵守：

// 正确使用 reserved 的示例
message User {
  reserved 2, 15, 9 to 11;  // 保留已删除的字段编号
  reserved "phone", "fax";  // 保留已删除的字段名

  int64  id   = 1;
  string name = 3;  // 注意：编号 2 已被保留，不能使用
}

3.7 Proto 文件整体结构图

下面的 SVG 图展示了 Proto 文件的完整结构层次，从文件头到具体的 message 和 service 定义：

3.8 完整 Proto 文件示例

综合以上知识点，下面是一个完整的 Proto 文件示例，包含 package、import、message 嵌套、枚举、service 流式接口：

syntax = "proto3";

package order.v1;

option go_package = "github.com/example/proto/gen/go/order/v1;orderv1";

import "google/protobuf/timestamp.proto";
import "common/v1/common.proto";

// 订单状态枚举
enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING     = 1;
  ORDER_STATUS_CONFIRMED   = 2;
  ORDER_STATUS_SHIPPED     = 3;
  ORDER_STATUS_DELIVERED   = 4;
  ORDER_STATUS_CANCELLED   = 5;
}

// 订单项
message OrderItem {
  int64    product_id = 1;
  string   product_name = 2;
  int32    quantity   = 3;
  double   unit_price = 4;
}

// 订单主结构
message Order {
  int64                          order_id   = 1;
  int64                          user_id    = 2;
  repeated OrderItem             items      = 3;
  OrderStatus                    status     = 4;
  double                         total_amount = 5;
  google.protobuf.Timestamp      created_at = 6;
  common.v1.Address              shipping_address = 7;
}

// 请求与响应
message CreateOrderRequest {
  int64          user_id = 1;
  repeated OrderItem items = 2;
  common.v1.Address shipping_address = 3;
}

message CreateOrderResponse {
  Order order = 1;
}

message GetOrderRequest {
  int64 order_id = 1;
}

message GetOrderResponse {
  Order order = 1;
}

message ListOrdersRequest {
  int64 user_id = 1;
  int32 page_size = 2;
  string page_token = 3;
}

message ListOrdersResponse {
  repeated Order orders = 1;
  string next_page_token = 2;
}

message OrderStreamRequest {
  int64 user_id = 1;
}

message OrderUpdate {
  int64 order_id = 1;
  OrderStatus new_status = 2;
  google.protobuf.Timestamp update_time = 3;
}

// 服务定义
service OrderService {
  // 一元：创建订单
  rpc CreateOrder (CreateOrderRequest) returns (CreateOrderResponse);

  // 一元：查询单个订单
  rpc GetOrder (GetOrderRequest) returns (GetOrderResponse);

  // 服务端流式：列出用户所有订单
  rpc ListOrders (ListOrdersRequest) returns (stream Order);

  // 双向流式：实时订单状态更新
  rpc OrderStatusStream (stream OrderStreamRequest) returns (stream OrderUpdate);
}

3.9 本章小结