报表导出架构：gRPC接口契约与异步导出链路设计 - 第2节

2.1 Proto 文件结构：从 package 到 service 的骨架

Protocol Buffers（protobuf）是 gRPC 的接口定义语言（IDL）。每个 gRPC 服务都从一个 .proto 文件开始，该文件定义了消息结构、字段类型和服务方法。理解 proto 文件的骨架是编写可维护接口契约的第一步。

2.1.1 标准 proto 文件结构

一个完整的 proto 文件通常包含以下部分，按出现顺序排列：

syntax = "proto3";                          // ① 语法版本声明

package export.v1;                          // ② 包声明（避免命名冲突）

import "google/protobuf/timestamp.proto";   // ③ 导入依赖
import "common/status.proto";

option go_package = "pb/export/v1;exportv1"; // ④ 语言特定选项

// ⑤ 消息定义
message ExportRequest {
  string report_id = 1;
  string format = 2;
}

message ExportResponse {
  string job_id = 1;
  int32 status_code = 2;
}

// ⑥ 服务定义
service ExportService {
  rpc CreateExport(ExportRequest) returns (ExportResponse);
}

2.2 消息类型定义：字段规则与标量类型

消息（message）是 protobuf 中最核心的数据结构。每个消息由一组字段组成，每个字段包含：字段规则、数据类型、字段名和唯一编号。

2.2.1 字段规则（Field Rules）

proto3 提供了三种字段规则，控制字段的基数（cardinality）：

message ExportJob {
  string job_id = 1;                    // singular（默认）
  optional string description = 2;      // optional（显式可缺失）
  repeated string recipient_emails = 3; // repeated（列表）
}

2.2.2 标量类型映射

protobuf 标量类型与各语言类型的映射关系是接口契约正确性的基础。以下是导出报表场景中最常用的类型对照：

2.3 字段编号：不可更改的契约指纹

每个字段必须有一个唯一的编号（field number），范围是 1 到 2²⁹-1（536,870,911）。编号在序列化时标识字段，一旦发布，永远不能修改或复用。

2.3.1 编号范围与编码效率

message ExportConfig {
  // 高频字段使用 1-15 编号
  string format = 1;          // 1 字节编码
  int32 page_size = 2;        // 1 字节编码
  bool compress = 3;          // 1 字节编码

  // 常规字段使用 16+ 编号
  string output_path = 16;    // 2 字节编码
  string file_name = 17;      // 2 字节编码

  // 预留编号用于未来扩展
  reserved 100 to 200;        // 预留编号段
  reserved "deprecated_field"; // 预留字段名
}

2.4 枚举与嵌套消息：构建复杂模型

2.4.1 枚举（Enum）

枚举用于定义一组预定义的常量值。proto3 中枚举的第一个值必须为 0，且建议命名为 ENUM_TYPE_UNSPECIFIED：

enum ExportFormat {
  EXPORT_FORMAT_UNSPECIFIED = 0;  // 必须存在，表示未指定
  EXPORT_FORMAT_CSV = 1;
  EXPORT_FORMAT_XLSX = 2;
  EXPORT_FORMAT_PDF = 3;
}

message ExportRequest {
  ExportFormat format = 1;
}

2.4.2 嵌套消息

消息可以嵌套定义，用于组织紧密相关的数据结构：

message ExportJob {
  message Metadata {
    string created_by = 1;
    google.protobuf.Timestamp created_at = 2;
    int32 retry_count = 3;
  }

  string job_id = 1;
  Metadata metadata = 2;
  repeated string recipient_emails = 3;
}

2.5 完整示例：导出报表的 proto 契约

以下是一个面向异步导出链路的完整 proto 文件，综合了本节所有知识点：

syntax = "proto3";

package export.report.v1;

import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";

option go_package = "pb/export/report/v1;reportv1";

// 导出格式枚举
enum ExportFormat {
  EXPORT_FORMAT_UNSPECIFIED = 0;
  EXPORT_FORMAT_CSV = 1;
  EXPORT_FORMAT_XLSX = 2;
  EXPORT_FORMAT_PDF = 3;
}

// 导出任务状态枚举
enum JobStatus {
  JOB_STATUS_UNSPECIFIED = 0;
  JOB_STATUS_PENDING = 1;
  JOB_STATUS_PROCESSING = 2;
  JOB_STATUS_COMPLETED = 3;
  JOB_STATUS_FAILED = 4;
}

// 导出请求
message CreateExportRequest {
  string report_id = 1;
  ExportFormat format = 2;
  optional string file_name = 3;
  repeated string recipient_emails = 4;
  bool compress = 5;
  google.protobuf.Int32Value page_size = 16; // 包装类型，可区分未设置与 0
}

// 导出响应
message CreateExportResponse {
  string job_id = 1;
  JobStatus status = 2;
  google.protobuf.Timestamp created_at = 3;
}

// 查询任务状态请求
message GetJobStatusRequest {
  string job_id = 1;
}

// 查询任务状态响应
message GetJobStatusResponse {
  string job_id = 1;
  JobStatus status = 2;
  optional string download_url = 3;
  optional string error_message = 4;
}

// 导出服务定义
service ExportService {
  rpc CreateExport(CreateExportRequest) returns (CreateExportResponse);
  rpc GetJobStatus(GetJobStatusRequest) returns (GetJobStatusResponse);
}

2.6 Proto 文件到代码的编译流程

理解 proto 文件如何转换为目标语言代码，有助于在架构设计阶段预判生成代码的结构：

2.7 向后兼容性：契约演进的黄金法则

proto 文件一旦被多个服务依赖，修改时必须遵守以下兼容性规则：

2.8 本章小结

Protocol Buffers 是 gRPC 接口契约的基石。掌握 proto 文件结构、消息类型定义、字段规则与类型映射，是设计可演进、高性能的异步导出链路的第一步。核心要点：

• 结构清晰：syntax → package → import → option → message → service
• 字段规则：singular（默认）、optional（可缺失）、repeated（列表）
• 编号管理：1-15 给高频字段，删除时用 reserved 标记
• 类型选择：时间用 google.protobuf.Timestamp，可空值用包装类型
• 兼容优先：新增字段永远安全，删除和修改类型永远危险