4. 接口契约设计原则：面向契约编程、版本兼容性、字段命名与类型选择

在分布式报表导出服务中，gRPC 接口契约是服务提供方与消费方之间的“硬约束”。本章围绕 面向契约编程（Contract-First）、版本兼容性、字段命名与类型选择 三大核心原则展开，帮助你在设计 .proto 文件时做出经得起迭代的决策。

4.1 面向契约编程：从 .proto 开始，而非从代码开始

面向契约编程要求团队先定义接口契约（.proto 文件），再生成服务端与客户端代码。这与传统“先写实现再抽接口”的模式完全相反。

4.2 版本兼容性：向后兼容与向前兼容

gRPC 使用 Protocol Buffers 作为序列化协议，天然支持一定程度的兼容性。但“天然支持”不等于“自动正确”，设计者必须理解两种兼容方向：

• 向后兼容（Backward Compatibility）： 新版本服务端能正确处理旧版本客户端发送的请求。这是最常见的升级场景。
• 向前兼容（Forward Compatibility）： 旧版本服务端能正确处理新版本客户端发送的请求。这在灰度发布、金丝雀部署中至关重要。

// 正确的废弃方式
message ExportRequest {
  reserved 2, 5, 10 to 15;        // 保留字段编号
  reserved "legacy_param", "old_flag"; // 保留字段名称
  
  string report_id = 1;
  // 字段编号 2 已被保留，不可复用
  string format = 3;
  // ...
}

4.3 字段命名与类型选择：可读性与性能的平衡

字段命名和类型选择直接影响接口的可读性、序列化性能以及未来的扩展成本。以下是在报表导出服务中总结的实践规则：

4.3.1 字段命名规范

• 使用 snake_case： Protobuf 官方推荐，例如 report_id、export_format。生成的 Java 代码会自动转为驼峰，TypeScript 保持 snake_case。
• 避免缩写歧义： exp_fmt 不如 export_format 清晰。在跨团队协作中，全称优于缩写。
• 布尔字段用肯定前缀： 使用 include_header 而非 no_header，避免双重否定。
• 枚举值使用全大写： FORMAT_PDF、FORMAT_EXCEL，并在枚举名称前加类型前缀防止冲突。

4.3.2 类型选择决策树

4.4 契约设计检查清单

在提交 .proto 文件评审前，逐项核对以下清单：

1. 字段编号： 1-15 用于频繁出现的字段（节省 1 字节），16-2047 用于可选或低频字段。不要复用已删除的编号。
2. 默认值语义： Protobuf 3 中 int 默认 0，string 默认 ""，bool 默认 false。如果业务上需要区分“未设置”和“零值”，使用 optional 或 wrapper 类型。
3. 枚举零值： 枚举的第一个值必须是 ENUM_TYPE_UNSPECIFIED = 0，用于表示未指定。
4. 向后兼容检查： 新增字段是否设置了合理默认值？是否使用了 reserved 标记废弃字段？
5. 向前兼容检查： 旧服务端能否安全忽略新字段？是否修改了已有字段的类型或编号？
6. 命名一致性： 所有 message 名称是否以 Request/Response 结尾？RPC 方法名是否动宾结构（如 ExportReport）？

接口契约设计不是一次性工作，而是伴随服务演进的持续治理过程。遵循面向契约编程、理解兼容性边界、审慎选择字段命名与类型，能让报表导出服务在长期迭代中保持稳定、可扩展的接口边界。