4. 服务定义：service关键字、RPC方法定义、一元RPC与流式RPC的proto定义

在BFF聚合服务中，gRPC接口的协议适配起点是Proto服务定义。通过service关键字声明一个RPC服务，并在其中定义若干RPC方法，每种方法可选择不同的调用模式（一元或流式）。本节将系统讲解Proto服务定义的核心语法、RPC方法签名规则，以及一元RPC与流式RPC的适用场景与定义方式。

4.1 service关键字与服务定义结构

在Proto3语法中，使用service关键字定义一个gRPC服务，内部包含一个或多个rpc方法。每个方法必须指定请求消息类型和响应消息类型。

syntax = "proto3";

package bff.user.v1;

// 定义请求消息
message GetUserRequest {
  string user_id = 1;
}

message GetUserResponse {
  string user_id = 1;
  string nickname = 2;
  int32 age = 3;
}

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

4.2 一元RPC（Unary RPC）定义

一元RPC是最常用的调用模式：客户端发送一个请求消息，服务端返回一个响应消息。适用于查询单个资源、提交表单、执行简单操作等场景。

// 一元RPC定义示例
service OrderService {
  // 查询订单详情
  rpc GetOrder(GetOrderRequest) returns (GetOrderResponse);

  // 创建新订单
  rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);

  // 取消订单
  rpc CancelOrder(CancelOrderRequest) returns (CancelOrderResponse);
}

4.3 流式RPC（Streaming RPC）定义

流式RPC支持在单个gRPC调用中传输多个消息。Proto3支持三种流式模式：服务端流式、客户端流式、双向流式。在BFF聚合服务中，服务端流式最为常用，用于返回列表数据或持续推送事件。

4.3.1 服务端流式RPC（Server Streaming）

客户端发送一个请求，服务端返回一个消息流（多个响应消息）。适用于分页查询、批量导出、实时通知推送等场景。

// 服务端流式RPC定义
service NotificationService {
  // 订阅用户通知流：客户端请求一次，服务端持续推送通知
  rpc SubscribeNotifications(SubscribeRequest) returns (stream Notification);

  // 批量查询订单：返回订单列表流
  rpc ListOrders(ListOrdersRequest) returns (stream Order);
}

4.3.2 客户端流式RPC（Client Streaming）

客户端发送一个消息流，服务端返回一个响应。适用于批量上传、日志收集、流式写入等场景。

// 客户端流式RPC定义
service LogService {
  // 批量上报日志：客户端发送多条日志，服务端返回汇总结果
  rpc ReportLogs(stream LogEntry) returns (ReportSummary);
}

4.3.3 双向流式RPC（Bidirectional Streaming）

客户端和服务端可以同时发送和接收消息流。适用于实时聊天、协同编辑、游戏状态同步等场景。

// 双向流式RPC定义
service ChatService {
  // 实时聊天：客户端和服务端双向发送消息
  rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

4.4 一元RPC与流式RPC的对比与选型

在BFF聚合服务中，选择一元RPC还是流式RPC，取决于数据量、实时性要求和客户端消费模式。以下对比表帮助决策：

4.5 完整proto服务定义示例（BFF聚合场景）

以下是一个BFF聚合服务中常见的proto定义，包含一元RPC和服务端流式RPC：

syntax = "proto3";

package bff.order.v1;

// ---------- 公共消息 ----------
message Order {
  string order_id = 1;
  string user_id = 2;
  double total_amount = 3;
  string status = 4;
  int64 create_time = 5;
}

message UserBrief {
  string user_id = 1;
  string nickname = 2;
}

// ---------- 一元RPC ----------
message GetOrderDetailRequest {
  string order_id = 1;
}

message GetOrderDetailResponse {
  Order order = 1;
  UserBrief user = 2;  // BFF聚合用户信息
}

// ---------- 服务端流式RPC ----------
message ListUserOrdersRequest {
  string user_id = 1;
  int32 page_size = 2;
  string page_token = 3;
}

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

// ---------- 服务定义 ----------
service BffOrderService {
  // 一元RPC：查询订单详情（聚合用户信息）
  rpc GetOrderDetail(GetOrderDetailRequest) returns (GetOrderDetailResponse);

  // 服务端流式RPC：分页查询用户订单列表
  rpc ListUserOrders(ListUserOrdersRequest) returns (stream ListUserOrdersResponse);
}

4.6 服务定义最佳实践

• 服务粒度适中：每个服务包含5~15个RPC方法，避免服务过于庞大或碎片化。
• 方法命名规范：使用动词+名词（如GetUser、CreateOrder），保持与HTTP REST风格对齐。
• 请求/响应消息独立：每个RPC方法使用专用的请求和响应消息，避免复用通用消息导致字段冗余。
• 流式模式显式声明：在方法注释中说明流式模式及预期行为，方便BFF适配层理解。
• 版本管理：在package中使用版本号（如v1），支持服务演进。