2. gRPC 基础回顾：Protocol Buffers 语法、.proto 文件定义、gRPC 四种通信模式

在模板引擎适配报表导出模块时，gRPC 作为高性能的远程过程调用框架，承担着客户端（报表前端/调度器）与服务端（模板引擎/导出执行器）之间的契约通信。本章系统回顾 gRPC 的核心基础：Protocol Buffers 语法、.proto 文件定义规范以及四种通信模式，为后续的接口契约集成打下坚实的技术基础。

2.1 Protocol Buffers 语法核心

Protocol Buffers（简称 Protobuf）是 gRPC 的接口定义语言（IDL）与序列化协议。它使用 .proto 文件定义数据结构和服务接口，具有语言中立、平台无关、序列化体积小、解析速度快的特点。

2.1.1 消息类型定义

Protobuf 使用 message 关键字定义结构化数据。每个字段由类型、字段名和字段编号组成。字段编号用于二进制编码标识，一旦发布不可随意修改。

syntax = "proto3";

package report.template;

// 报表导出请求
message ExportRequest {
  string template_id = 1;          // 模板唯一标识
  string format = 2;               // 导出格式：pdf / excel / html
  map<string, string> params = 3;  // 动态参数键值对
  int32 timeout_seconds = 4;       // 超时时间
  bool include_watermark = 5;      // 是否包含水印
}

// 报表导出响应
message ExportResponse {
  string job_id = 1;               // 导出任务ID
  bytes file_content = 2;          // 文件二进制内容
  int64 file_size = 3;             // 文件大小（字节）
  string mime_type = 4;            // MIME类型
}

2.1.2 标量类型与枚举

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

枚举类型使用 enum 关键字定义，必须从 0 开始作为默认值：

enum ExportFormat {
  EXPORT_FORMAT_UNSPECIFIED = 0;  // 未指定
  PDF = 1;
  EXCEL = 2;
  HTML = 3;
  CSV = 4;
}

2.2 .proto 文件定义规范

.proto 文件是 gRPC 服务的契约文件，包含包声明、导入依赖、消息定义和服务定义四个核心部分。良好的文件组织直接影响接口的可维护性和跨团队协作效率。

2.2.1 文件结构模板

syntax = "proto3";                          // 指定语法版本

package report.template.v1;                 // 包名，避免命名冲突

import "google/protobuf/timestamp.proto";   // 导入标准类型
import "common/status.proto";               // 导入公共消息

option go_package = "report/template/v1;templatev1";
option java_package = "com.report.template.v1";
option java_multiple_files = true;

// 服务定义
service TemplateExportService {
  // 方法声明
  rpc ExportReport (ExportRequest) returns (ExportResponse);
}

// 请求消息
message ExportRequest {
  string template_id = 1;
  ExportFormat format = 2;
  map<string, string> params = 3;
}

// 响应消息
message ExportResponse {
  string job_id = 1;
  ExportStatus status = 2;
  bytes file_content = 3;
}

2.2.2 命名规范与最佳实践

• 文件命名：使用小写蛇形命名，如 template_export.proto，与包名对应。
• 消息命名：使用大驼峰命名，如 ExportRequest、ExportResponse。
• 字段命名：使用小写蛇形命名，如 template_id、file_content。
• 枚举命名：枚举类型使用大驼峰，枚举值使用全大写加下划线，且以枚举类型名为前缀。
• 服务命名：使用大驼峰，以 Service 结尾，如 TemplateExportService。
• RPC 方法命名：使用大驼峰动词短语，如 ExportReport、GetExportStatus。

2.3 gRPC 四种通信模式

gRPC 基于 HTTP/2 协议，支持四种通信模式，覆盖从简单请求-响应到复杂流式交互的全部场景。在报表导出模块中，不同模式适用于不同的业务需求。

2.3.1 模式对比总览

通信模式	客户端请求	服务端响应	典型场景
Unary（一元）	单条消息	单条消息	简单报表导出、查询任务状态
Server Streaming（服务端流）	单条消息	多条消息流	大文件分块下载、日志推送
Client Streaming（客户端流）	多条消息流	单条消息	批量上传模板、分段提交参数
Bidirectional Streaming（双向流）	多条消息流	多条消息流	实时报表预览、交互式数据管道

2.3.2 四种模式详解

1. Unary（一元模式）

客户端发送一个请求，服务端返回一个响应。这是最基础的 RPC 模式，适用于请求和响应数据量较小的场景。

service TemplateExportService {
  // 一元模式：请求单个模板ID，返回导出结果
  rpc ExportReport (ExportRequest) returns (ExportResponse);
}

2. Server Streaming（服务端流模式）

客户端发送一个请求，服务端以流的形式返回多个响应消息。适用于大文件导出、实时进度推送等场景。

service TemplateExportService {
  // 服务端流：请求导出，服务端分块返回文件内容
  rpc ExportLargeReport (ExportRequest) returns (stream FileChunk);
}

message FileChunk {
  int32 chunk_index = 1;
  bytes data = 2;
  bool is_last = 3;
}

3. Client Streaming（客户端流模式）

客户端以流的形式发送多个请求消息，服务端在所有消息接收完毕后返回一个响应。适用于批量数据提交、分段上传等场景。

service TemplateExportService {
  // 客户端流：客户端分段上传模板片段，服务端合并后返回结果
  rpc UploadTemplate (stream TemplateChunk) returns (UploadResponse);
}

message TemplateChunk {
  int32 chunk_index = 1;
  bytes content = 2;
  string template_id = 3;
}

4. Bidirectional Streaming（双向流模式）

客户端和服务端可以同时发送和接收多条消息，双方独立读写。适用于实时协作、交互式查询等场景。

service TemplateExportService {
  // 双向流：客户端实时发送参数调整，服务端实时返回预览结果
  rpc PreviewReport (stream PreviewRequest) returns (stream PreviewResponse);
}

message PreviewRequest {
  string param_key = 1;
  string param_value = 2;
}

message PreviewResponse {
  bytes preview_image = 1;
  int32 page_number = 2;
  string render_status = 3;
}

2.3.3 通信模式选择决策流程

2.4 gRPC 服务定义与接口契约

在 .proto 文件中使用 service 关键字定义 gRPC 服务，内部包含一个或多个 RPC 方法。每个方法必须指定输入消息类型和输出消息类型，并使用 stream 关键字标识流式通信。

2.4.1 完整服务契约示例

syntax = "proto3";

package report.export.v1;

import "google/protobuf/empty.proto";

option go_package = "report/export/v1;exportv1";

// 报表导出服务 —— 完整契约
service ReportExportService {
  // 一元模式：同步导出报表
  rpc ExportSync (ExportRequest) returns (ExportResponse);

  // 服务端流：异步导出，分块下载大文件
  rpc ExportStream (ExportRequest) returns (stream FileChunk);

  // 客户端流：批量提交导出任务
  rpc BatchExport (stream ExportRequest) returns (BatchSummary);

  // 双向流：实时预览报表
  rpc PreviewReport (stream PreviewParam) returns (stream PreviewResult);
}

message ExportRequest {
  string template_id = 1;
  string format = 2;
  map<string, string> parameters = 3;
}

message ExportResponse {
  string job_id = 1;
  bytes data = 2;
  int64 size = 3;
}

message FileChunk {
  int32 sequence = 1;
  bytes content = 2;
  bool is_final = 3;
}

message BatchSummary {
  int32 total_count = 1;
  int32 success_count = 2;
  int32 fail_count = 3;
  repeated string failed_ids = 4;
}

message PreviewParam {
  string key = 1;
  string value = 2;
}

message PreviewResult {
  bytes page_image = 1;
  int32 page_index = 2;
  string status = 3;
}

2.4.2 接口契约集成要点

• 版本管理：在包名或文件路径中加入版本号（如 v1、v2），支持多版本共存和平滑升级。
• 错误处理：gRPC 内置标准错误码（如 NOT_FOUND、INVALID_ARGUMENT、INTERNAL），可在响应消息中附加详细错误信息。
• 超时与重试：客户端应设置合理的超时时间（如 30s），服务端通过 google.protobuf.Duration 传递建议超时。
• 元数据传递：使用 gRPC 元数据（Metadata）传递认证令牌、请求ID、追踪信息等跨切面数据，不污染业务消息体。

2.5 本章小结

本章系统回顾了 gRPC 的核心基础：

• Protocol Buffers 语法：掌握消息类型、标量类型、枚举和字段编号规则，确保数据结构定义准确高效。
• .proto 文件定义规范：遵循包管理、命名规范和向后兼容原则，维护接口契约的稳定性和可读性。
• 四种通信模式：Unary 适用于简单请求-响应；Server Streaming 适用于大文件分块；Client Streaming 适用于批量提交；Bidirectional Streaming 适用于实时交互。
• 接口契约集成：.proto 文件作为唯一可信契约，通过 protoc 编译器生成客户端 Stub 和服务端骨架，实现语言无关的跨平台通信。