3. 服务契约(Contract)的定义：proto文件作为契约中心

在gRPC生态中，服务契约（Service Contract）是客户端与服务端之间的“法律文件”。它使用Protocol Buffers（简称Protobuf）的.proto文件明确定义了服务接口、消息结构、字段类型、枚举值以及RPC方法签名。契约一旦发布，双方必须严格遵守，任何修改都需要经过版本管理和兼容性审查。

3.1 契约中心的结构设计

一个标准化的Go项目通常将proto文件集中放置在api/或proto/目录下，按服务模块、版本号进行分层组织。以下是一个推荐的项目结构示例：

my-grpc-service/
├── api/                          # 契约中心
│   ├── helloworld/
│   │   ├── v1/
│   │   │   ├── helloworld.proto
│   │   │   └── helloworld_grpc.proto  # 由protoc生成
│   │   └── v2/
│   │       ├── helloworld.proto
│   │       └── helloworld_grpc.proto
│   └── common/
│       └── v1/
│           └── types.proto       # 共享消息类型
├── internal/                     # 业务实现
├── cmd/                          # 入口
└── buf.gen.yaml                  # Buf配置（可选）

3.2 版本管理策略

gRPC契约的版本管理通常采用语义化版本（SemVer）与包路径版本化相结合的方式。下表对比了两种主流策略：

3.3 向后兼容性策略

契约的向后兼容性是压测和线上服务稳定的基石。gRPC官方推荐遵循以下兼容性规则：

• 允许的变更：
  • 新增字段（必须使用新的field number，且不能复用已删除的编号）
  • 新增RPC方法
  • 新增枚举值（客户端需处理未知枚举值）
  • 将optional字段改为repeated（仅限proto3）
• 禁止的变更：
  • 删除或修改已有字段的编号
  • 修改字段类型（如int32改为string）
  • 修改RPC方法的请求/响应消息类型
  • 修改oneof中的字段编号

3.4 契约与压测的闭环关系

在压测场景中，契约中心直接驱动压测脚本的生成。以下SVG图展示了从proto文件到压测执行的完整闭环：

3.5 契约变更流程

当业务需求变更需要修改proto文件时，建议遵循以下标准化流程：

1. 评估影响范围：检查变更是否属于向后兼容，使用buf breaking工具扫描。
2. 创建新版本：如果变更不兼容，在v2/目录下创建新proto文件，保留v1/不变。
3. 更新压测基线：根据新契约重新生成压测脚本，确保压测数据与最新接口匹配。
4. 灰度发布：服务端同时支持v1和v2，客户端逐步迁移。
5. 废弃旧版本：确认所有客户端迁移完成后，标记旧版本为deprecated，并在后续大版本中移除。

3.6 契约即文档

proto文件本身就是最权威的API文档。通过protoc的--doc_out插件或buf的文档生成功能，可以自动生成HTML/PDF格式的API手册。以下是一个proto文件中的注释规范示例：

syntax = "proto3";

package helloworld.v1;

option go_package = "github.com/example/my-grpc-service/api/helloworld/v1;helloworldv1";

// Greeter服务提供简单的问候功能。
// 用于演示gRPC契约定义与压测集成。
service Greeter {
  // SayHello向用户发送问候。
  // 请求参数：name - 用户名，必填，长度1-100。
  // 响应：message - 问候语，格式为"Hello, {name}"。
  rpc SayHello (HelloRequest) returns (HelloReply);
}

// HelloRequest是SayHello方法的请求消息。
message HelloRequest {
  string name = 1;  // 用户名，必填，长度1-100
}

// HelloReply是SayHello方法的响应消息。
message HelloReply {
  string message = 1;  // 问候语
}