4. gRPC 接口契约设计原则：向后兼容性、字段编号管理、枚举与 oneof 使用

在异步导出链路中，gRPC 接口契约是服务提供方与消费方之间的“永久协议”。一旦上线，契约的变更将直接影响所有下游客户端。本章聚焦于四个核心设计原则：向后兼容性、字段编号管理、枚举与 oneof 的正确使用。这些原则决定了导出链路能否在长期迭代中保持稳定、无中断升级。

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

gRPC 使用 Protocol Buffers（protobuf）作为接口定义语言（IDL）。protobuf 的二进制编码设计天然支持部分兼容性，但开发者仍需遵循明确的规则，否则会导致客户端解析失败或数据丢失。

向后兼容性分为两个方向：

• 向前兼容（Forward Compatibility）： 老客户端读取新服务端发送的消息时，能忽略未知字段，不崩溃。
• 向后兼容（Backward Compatibility）： 新客户端读取老服务端发送的消息时，能正确解析已知字段，缺失的字段使用默认值。

4.2 字段编号管理：小数字段的高效策略

protobuf 中字段编号（1 到 2^29-1）直接影响编码效率和消息大小。编号 1-15 使用 1 字节编码，16-2047 使用 2 字节编码。对于高频字段，应优先分配小编号。

// 推荐：高频字段使用小编号
message ExportRequest {
  string export_id = 1;          // 1 字节
  string user_id = 2;            // 1 字节
  string file_format = 3;        // 1 字节
  int64 start_time = 4;          // 1 字节
  int64 end_time = 5;            // 1 字节
  // 预留 6-15 给未来高频字段
  string callback_url = 16;      // 2 字节
  map<string, string> extra_params = 17; // 2 字节
}

字段编号管理的最佳实践：

• 预留区间： 将 1-15 保留给核心、高频字段；16-31 给次核心字段；32+ 给扩展或低频字段。
• 使用 reserved： 删除字段时，必须同时保留编号和字段名，防止未来冲突。
• 避免大编号： 编号超过 19000 会触发 protobuf 保留区间（19000-19999），不可使用。

// 正确使用 reserved 的示例
message ExportRequest {
  reserved 6, 7, 8;              // 保留已删除字段的编号
  reserved "deprecated_field";   // 保留已删除字段的名称
  string export_id = 1;
  string user_id = 2;
  // 新增字段使用新编号 9
  string priority = 9;
}

4.3 枚举（Enum）的正确使用与兼容性陷阱

枚举在 gRPC 契约中用于表示有限状态集，如导出状态、文件格式类型。但枚举的兼容性规则比普通字段更严格。

enum ExportStatus {
  EXPORT_STATUS_UNSPECIFIED = 0;  // 必须存在，作为默认值
  EXPORT_STATUS_PENDING = 1;
  EXPORT_STATUS_PROCESSING = 2;
  EXPORT_STATUS_COMPLETED = 3;
  EXPORT_STATUS_FAILED = 4;
}

枚举设计原则：

• 零值语义化： 第一个枚举值必须为 UNSPECIFIED（0），表示未设置或未知状态。客户端收到 0 时应做兜底处理。
• 禁止删除枚举值： 删除枚举值会导致老数据中的该值被解析为未知枚举，客户端可能 panic。
• 使用 reserved 管理枚举： 与字段编号一样，删除的枚举值必须用 reserved 标记。
• 新增枚举值： 新增值使用新的编号，老客户端会将其识别为未知枚举，需在代码中处理 UNRECOGNIZED 分支。

// 枚举兼容性示例
enum ExportStatus {
  reserved 5, 6;                 // 保留已删除的枚举值编号
  reserved "EXPORT_STATUS_CANCELLED"; // 保留已删除的枚举值名称
  EXPORT_STATUS_UNSPECIFIED = 0;
  EXPORT_STATUS_PENDING = 1;
  EXPORT_STATUS_PROCESSING = 2;
  EXPORT_STATUS_COMPLETED = 3;
  EXPORT_STATUS_FAILED = 4;
  // 新增枚举值
  EXPORT_STATUS_PAUSED = 7;
}

4.4 Oneof 的使用：互斥字段的契约表达

oneof 用于表示一组互斥字段，同一时刻只能设置其中一个。在导出链路中，常用于区分不同的导出目标、不同的过滤条件或不同的错误类型。

message ExportResponse {
  string export_id = 1;
  oneof result {
    string download_url = 10;     // 导出成功时返回
    ErrorDetail error = 11;       // 导出失败时返回
  }
}

message ErrorDetail {
  int32 error_code = 1;
  string error_message = 2;
}

oneof 设计要点：

• 编号隔离： oneof 内的字段编号必须与消息顶层字段编号不重叠。建议使用独立编号区间（如 10-20）。
• 兼容性限制： 不能将 oneof 中的字段移出，也不能将外部字段移入 oneof，这会导致编号冲突和解析错误。
• 默认值行为： 如果 oneof 中没有任何字段被设置，则 HasField() 返回 false。客户端必须检查 oneof 的具体 case。
• 新增 oneof 分支： 可以在 oneof 末尾新增字段，老客户端会忽略未知分支。

// 导出过滤条件中使用 oneof
message ExportFilter {
  oneof filter_type {
    string date_range = 10;       // 按日期范围过滤
    string user_group = 11;       // 按用户组过滤
    string report_id = 12;        // 按报表 ID 过滤
  }
}

4.5 契约设计综合示例：导出请求与响应

以下综合示例展示了向后兼容性、字段编号管理、枚举与 oneof 在导出链路中的协同使用：

syntax = "proto3";

package export.v1;

// 导出状态枚举
enum ExportStatus {
  EXPORT_STATUS_UNSPECIFIED = 0;
  EXPORT_STATUS_PENDING = 1;
  EXPORT_STATUS_PROCESSING = 2;
  EXPORT_STATUS_COMPLETED = 3;
  EXPORT_STATUS_FAILED = 4;
  reserved 5, 6;
}

// 导出请求
message ExportRequest {
  // 核心字段：使用小编号
  string request_id = 1;
  string user_id = 2;
  string file_format = 3;        // "csv", "xlsx", "pdf"
  int64 start_time = 4;
  int64 end_time = 5;

  // 预留编号 6-9 给未来核心字段
  reserved 6, 7, 8, 9;

  // oneof 用于互斥的导出目标
  oneof destination {
    string callback_url = 10;
    string storage_path = 11;
  }

  // 扩展字段：使用大编号
  map<string, string> extra_params = 32;
}

// 导出响应
message ExportResponse {
  string request_id = 1;
  ExportStatus status = 2;
  int32 progress_percent = 3;

  oneof result {
    string download_url = 10;
    ErrorDetail error = 11;
  }
}

message ErrorDetail {
  int32 error_code = 1;
  string error_message = 2;
}

4.6 常见兼容性陷阱与规避策略