📚 课程目录第3章 gRPC基础回顾

3. gRPC基础回顾

在构建报表导出服务之前，必须扎实掌握 gRPC 的两大基石：Protocol Buffers（protobuf） 接口定义语言，以及 gRPC 的四种通信模式。本章将系统回顾这些核心概念，为后续的接口契约设计打下基础。

3.1 Protocol Buffers 语法速览

Protocol Buffers 是一种语言无关、平台无关的序列化结构数据格式，用于定义服务接口和消息结构。其核心文件以 .proto 为后缀。

3.1.1 消息结构定义

一个典型的 protobuf 消息包含字段编号、字段类型和字段名称。字段编号是二进制编码的关键，一旦使用不应更改。

syntax = "proto3";

package reportexport;

// 定义导出请求消息
message ExportRequest {
  string report_id = 1;          // 报表唯一标识
  string format = 2;             // 导出格式：PDF, CSV, XLSX
  int32 page_size = 3;           // 分页大小（可选）
  bool include_charts = 4;       // 是否包含图表
}

// 定义导出响应消息
message ExportResponse {
  string job_id = 1;             // 异步任务ID
  string download_url = 2;       // 下载链接（任务完成后填充）
  ExportStatus status = 3;       // 当前任务状态
}

// 枚举类型
enum ExportStatus {
  EXPORT_STATUS_UNSPECIFIED = 0;
  PENDING = 1;
  PROCESSING = 2;
  COMPLETED = 3;
  FAILED = 4;
}

3.1.2 标量类型与字段规则

Protobuf 类型	对应语言（Go）	对应语言（Java）	说明
`double`	float64	double	64位浮点数
`float`	float32	float	32位浮点数
`int32`	int32	int	可变长编码，负数效率低
`int64`	int64	long	可变长编码
`string`	string	String	UTF-8 编码文本
`bytes`	[]byte	ByteString	任意二进制数据
`bool`	bool	boolean	布尔值

字段规则提示： proto3 中所有字段默认为 optional，且不支持 required。使用 repeated 关键字表示数组（列表）。字段编号 1-15 使用 1 字节编码，应留给频繁出现的字段。

3.1.3 服务定义与 RPC 方法签名

在 protobuf 中，服务使用 service 关键字定义，每个 RPC 方法需指定输入消息和输出消息类型。

service ReportExportService {
  // 一元 RPC：同步导出
  rpc ExportReport(ExportRequest) returns (ExportResponse);

  // 服务端流式 RPC：导出进度推送
  rpc ExportProgress(ExportRequest) returns (stream ProgressEvent);

  // 客户端流式 RPC：批量上传报表片段
  rpc UploadReportChunks(stream ChunkData) returns (UploadResponse);

  // 双向流式 RPC：实时交互式导出配置
  rpc InteractiveExport(stream ConfigCommand) returns (stream ExportEvent);
}

3.2 gRPC 四种通信模式详解

gRPC 基于 HTTP/2 协议，支持四种通信模式，分别适用于不同的业务场景。理解这些模式是设计高效报表导出服务的前提。

3.2.1 模式对比总览

通信模式	客户端请求	服务端响应	典型场景	报表导出适用性
Unary（一元）	单条消息	单条消息	简单查询、同步操作	提交导出任务、查询任务状态
Server Streaming（服务端流）	单条消息	消息流	推送日志、进度通知	导出进度推送、数据分片下发
Client Streaming（客户端流）	消息流	单条消息	批量上传、数据聚合	上传大报表模板、批量提交导出请求
Bidirectional Streaming（双向流）	消息流	消息流	实时交互、双向推送	实时配置导出参数、动态过滤数据

3.2.2 模式一：Unary RPC（一元模式）

客户端发送一个请求，服务端返回一个响应。这是最基础的 RPC 模式，行为与传统的 HTTP REST 接口类似。

  报表导出场景： 客户端调用 ExportReport 提交导出任务，服务端立即返回 job_id 和初始状态。后续客户端通过另一个 Unary RPC 轮询任务状态。

3.2.3 模式二：Server Streaming RPC（服务端流模式）

客户端发送一个请求，服务端返回一个消息流。服务端可以持续推送数据，直到流结束。

  报表导出场景： 客户端请求导出进度，服务端通过 ExportProgress 流式推送 ProgressEvent（如 10%、50%、90%、100%），客户端实时更新进度条。

3.2.4 模式三：Client Streaming RPC（客户端流模式）

客户端发送一个消息流，服务端接收完所有消息后返回一个响应。

  报表导出场景： 客户端将大报表模板拆分为多个 ChunkData 分片，通过 UploadReportChunks 流式上传，服务端合并后返回 UploadResponse（包含合并后的文件 ID）。

3.2.5 模式四：Bidirectional Streaming RPC（双向流模式）

客户端和服务端可以独立地发送和接收消息流，实现全双工通信。双方可以按任意顺序读写。

  报表导出场景： 客户端通过 InteractiveExport 发送 ConfigCommand（如设置过滤条件、切换图表类型），服务端实时返回 ExportEvent（如预览数据、错误提示），实现交互式导出配置。

3.3 四种模式的选择策略

在报表导出服务中，不同阶段适合不同的通信模式。以下选择策略可帮助架构师做出合理决策：

任务提交（Unary）： 客户端提交导出请求，服务端返回任务 ID。简单、可靠，适合非阻塞的异步任务启动。
进度推送（Server Streaming）： 服务端主动推送导出进度。避免客户端轮询，降低网络开销，提升用户体验。
大文件上传（Client Streaming）： 客户端分片上传报表模板或数据源。支持断点续传，减少内存占用。
实时配置（Bidirectional Streaming）： 客户端动态调整导出参数，服务端实时反馈预览或错误。适合复杂报表的交互式设计。

设计警告： 双向流虽然功能强大，但增加了服务端状态管理的复杂度。在报表导出服务中，建议优先使用 Unary + Server Streaming 的组合，仅在需要实时交互的场景才引入双向流。避免过度设计导致系统难以维护。

3.4 本章小结

本章系统回顾了 Protocol Buffers 的核心语法，包括消息结构、标量类型、枚举和服务定义。同时深入分析了 gRPC 的四种通信模式：Unary、Server Streaming、Client Streaming 和 Bidirectional Streaming，并结合报表导出场景给出了具体应用示例。掌握这些基础概念，是后续设计报表导出服务接口契约和异步任务通信架构的前提。