📚 课程目录第4章 gRPC服务定义与代码生成

4. gRPC 服务定义与代码生成

在 gRPC 压测闭环中，服务定义是一切通信的契约。本章将完整演示如何编写 .proto 文件、安装 Go 插件链，并通过 protoc 生成可直接用于压测的 Go 桩代码。

4.1 编写 .proto 文件：定义服务契约

.proto 文件使用 Protocol Buffers 语法，同时描述消息结构和 RPC 方法签名。以下是一个面向压测场景的示例，包含一元调用和服务器端流式调用两种模式：

syntax = "proto3";

package benchmark;

option go_package = "github.com/example/benchmark/proto";

// 压测请求：携带负载大小与并发标识
message LoadRequest {
  string client_id = 1;
  int32 payload_bytes = 2;
  int64 send_timestamp = 3;
}

// 压测响应：返回服务端处理耗时
message LoadResponse {
  string server_id = 1;
  int64 receive_timestamp = 2;
  int64 process_duration_ns = 3;
}

// 压测服务定义
service LoadTest {
  // 一元 RPC：单请求-单响应
  rpc UnaryLoad(LoadRequest) returns (LoadResponse);

  // 服务器端流式 RPC：单请求-流响应，适合压测吞吐
  rpc StreamLoad(LoadRequest) returns (stream LoadResponse);
}

压测字段设计要点：send_timestamp 与 receive_timestamp 配合可精确计算网络往返耗时；payload_bytes 用于控制消息体大小，模拟不同负载场景。

4.2 安装 Go 插件链

生成 Go gRPC 代码需要三个核心工具，缺一不可。下表列出各工具的安装方式与版本验证命令：

工具	安装命令	验证命令	最低版本要求
`protoc`	从 GitHub Releases 下载二进制，或通过系统包管理器安装	`protoc --version`	≥ 3.21.0
`protoc-gen-go`	`go install google.golang.org/protobuf/cmd/protoc-gen-go@latest`	`protoc-gen-go --version`	≥ 1.28.0
`protoc-gen-go-grpc`	`go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest`	`protoc-gen-go-grpc --version`	≥ 1.2.0

常见陷阱：务必确保 $GOPATH/bin 已加入 PATH 环境变量，否则 protoc 无法找到插件。执行 which protoc-gen-go-grpc 确认路径正确。

4.3 使用 protoc 生成 Go 代码

在项目根目录下创建 proto/ 文件夹，将 .proto 文件放入其中。执行以下命令生成 Go 桩代码：

protoc --go_out=. \
       --go_opt=paths=source_relative \
       --go-grpc_out=. \
       --go-grpc_opt=paths=source_relative \
       proto/benchmark.proto

生成成功后，proto/ 目录下会新增两个文件：

benchmark.pb.go — 消息结构的 Go 结构体定义、序列化/反序列化方法。
benchmark_grpc.pb.go — 客户端桩代码（LoadTestClient）与服务端注册代码（LoadTestServer）。

4.4 代码生成产物结构

以下 SVG 展示了从 .proto 到 Go 桩代码的完整生成链路，以及每个产物的核心职责：

4.5 项目结构规范

为支撑压测闭环，推荐按以下目录组织 Go 项目：

benchmark-project/
├── proto/
│   ├── benchmark.proto        # 服务定义源文件
│   ├── benchmark.pb.go        # 生成：消息结构
│   └── benchmark_grpc.pb.go   # 生成：gRPC 桩代码
├── server/
│   └── main.go                # 被测服务实现
├── client/
│   └── main.go                # 压测客户端入口
├── go.mod
└── go.sum

  压测闭环关键点：将 proto/ 目录视为独立模块，使用 go.mod 管理依赖。每次修改 .proto 后，重新运行 protoc 命令并 go mod tidy 同步依赖，确保桩代码与压测脚本始终一致。

4.6 验证生成结果

在 Go 代码中引用生成的桩代码，快速验证链路是否打通：

package main

import (
    "fmt"
    "github.com/example/benchmark/proto"
)

func main() {
    req := &proto.LoadRequest{
        ClientId:      "load-tester-01",
        PayloadBytes:  1024,
        SendTimestamp: 1700000000,
    }
    fmt.Printf("请求消息已创建: %+v\n", req)
}

若编译通过且无导入错误，说明 .proto 定义、插件安装、代码生成三步全部正确，压测闭环的契约层已就绪。