4. Proto 文件设计原则：报表导出服务的接口定义规范

在 gRPC 微服务架构中，Proto 文件是服务契约的基石。对于报表导出服务，Proto 文件的设计直接决定了接口的扩展性、兼容性和团队协作效率。本章将围绕命名空间、包名、版本管理以及通用消息体定义展开，建立一套可长期演进的接口规范。

4.1 命名空间与包名规范

命名空间用于避免不同团队、不同领域之间的消息类型冲突。包名则对应 Proto 文件中的 package 关键字，影响生成代码的命名空间（如 Java 的 package、Go 的 module path）。

推荐包名格式：

package com.company.reporting.export.v1;

此包名映射到 Java 的 com.company.reporting.export.v1，Go 的 com/company/reporting/export/v1。所有消息和服务定义均在此包下，避免与报表查询、报表调度等其他服务产生命名冲突。

4.2 版本管理策略：v1 / v2

gRPC 接口的版本管理不同于 RESTful API 的 URL 路径版本。Proto 文件通过包名中的版本号和独立的 proto 目录实现多版本共存。

4.2.1 目录结构

proto/
  com/company/reporting/export/
    v1/
      export_service.proto
      export_common.proto
    v2/
      export_service.proto
      export_common.proto

4.2.2 版本演进原则

• 向后兼容：v1 接口一旦发布，不允许删除字段或修改字段类型。新增字段必须使用 optional 或 repeated 修饰。
• 大版本升级：当需要破坏性变更（如删除 RPC 方法、修改请求语义）时，创建 v2 目录，v1 继续维护至废弃周期结束。
• 客户端协商：客户端通过 gRPC 的 resolver 或配置中心指定调用的版本号，服务端同时注册 v1 和 v2 的 Service。

4.3 通用 ExportRequest / ExportResponse 消息体

报表导出服务的核心接口是 ExportReport RPC。为了统一不同报表类型的入参和出参，需要设计一套通用的请求/响应消息体，同时保留扩展点。

4.3.1 ExportRequest 定义

message ExportRequest {
  // 报表唯一标识，由报表元数据服务分配
  string report_id = 1;

  // 导出格式，支持 pdf / excel / csv / html
  ExportFormat format = 2;

  // 查询参数，key-value 结构，用于动态过滤条件
  map<string, string> query_params = 3;

  // 导出选项，控制分页、排序、水印等行为
  ExportOptions options = 4;

  // 扩展字段，用于未来新增参数而不破坏兼容性
  google.protobuf.Any extension = 5;
}

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

message ExportOptions {
  // 是否包含表头
  bool include_header = 1;

  // 最大行数，0 表示不限制
  int32 max_rows = 2;

  // 排序字段列表
  repeated string sort_by = 3;

  // 水印文本，空表示无水印
  string watermark = 4;
}

4.3.2 ExportResponse 定义

message ExportResponse {
  // 导出任务 ID，用于异步轮询或追踪
  string task_id = 1;

  // 导出状态
  ExportStatus status = 2;

  // 文件下载 URL（同步模式时直接返回）
  string download_url = 3;

  // 错误信息，仅 status 为 FAILED 时有值
  string error_message = 4;

  // 文件元数据
  FileMeta file_meta = 5;
}

enum ExportStatus {
  EXPORT_STATUS_UNSPECIFIED = 0;
  SUCCEEDED = 1;
  FAILED = 2;
  PENDING = 3;
  PROCESSING = 4;
}

message FileMeta {
  string file_name = 1;
  int64 file_size_bytes = 2;
  string content_type = 3;
  int64 expires_at_timestamp = 4;
}

4.4 消息体设计原则总结

4.5 接口定义与消费组关系图

下图展示了 Proto 文件定义、版本管理、通用消息体与消费组之间的整体关系：

4.6 服务定义示例

将上述消息体组合为完整的 gRPC 服务定义：

package com.company.reporting.export.v1;

service ExportService {
  // 同步导出：适用于小数据量，直接返回下载 URL
  rpc ExportReport(ExportRequest) returns (ExportResponse);

  // 异步导出：适用于大数据量，返回 task_id 后轮询
  rpc AsyncExportReport(ExportRequest) returns (ExportResponse);

  // 查询导出任务状态
  rpc GetExportTaskStatus(GetTaskStatusRequest) returns (ExportResponse);
}

message GetTaskStatusRequest {
  string task_id = 1;
}

4.7 本章小结