2. Go 开发环境搭建：工具链与协议编译栈

gRPC 开发依赖一套精确的工具链：Go 语言运行时、模块管理、协议缓冲区编译器以及对应的代码生成插件。本章将按依赖顺序搭建完整环境，确保后续章节的契约定义与代码生成能够一次通过。

2.1 Go 语言安装与版本选择

推荐使用 Go 1.21+，该版本内置了 toolchain 指令，可自动管理 Go 版本与模块兼容性。安装步骤如下：

1. 访问 go.dev/dl 下载对应操作系统的安装包（Linux 使用 .tar.gz，macOS 使用 .pkg，Windows 使用 .msi）。
2. Linux/macOS 解压至 /usr/local/go，并将 /usr/local/go/bin 加入 PATH。
3. 验证安装：go version 应输出类似 go version go1.22.2 linux/amd64。

2.2 Go Module 配置与代理加速

Go Module 是 gRPC 项目的依赖管理基石。初始化一个模块：

mkdir grpc-contract-lab && cd grpc-contract-lab
go mod init github.com/yourname/grpc-contract-lab

国内网络环境下必须配置 Go 代理，否则 google.golang.org/protobuf 等包无法下载：

go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=sum.golang.org

2.3 protoc 编译器安装

protoc 是 Protocol Buffers 的官方编译器，负责将 .proto 文件解析并生成中间表示（FileDescriptorProto），供后端插件消费。

安装后务必确认 protoc --version 输出 libprotoc 25.3 或更高版本。低于 3.21 的版本不支持 proto3 的 optional 关键字，会导致 gRPC 服务定义编译失败。

2.4 protoc-gen-go 与 protoc-gen-go-grpc 插件

这两个插件是 protoc 与 Go 之间的桥梁：

• protoc-gen-go：生成 .pb.go 消息结构体与序列化代码。
• protoc-gen-go-grpc：生成 _grpc.pb.go 服务端/客户端桩代码。

安装命令（Go 1.21+ 推荐使用 go install）：

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

安装后检查 $GOPATH/bin（默认 ~/go/bin）是否在 PATH 中：

which protoc-gen-go
# 应输出类似 /home/user/go/bin/protoc-gen-go

2.5 环境验证：编译一个最小 proto 文件

创建 proto/hello/v1/hello.proto：

syntax = "proto3";
package hello.v1;

option go_package = "github.com/yourname/grpc-contract-lab/gen/hello/v1;hellov1";

message SayHelloRequest {
  string name = 1;
}

message SayHelloResponse {
  string greeting = 1;
}

service Greeter {
  rpc SayHello (SayHelloRequest) returns (SayHelloResponse);
}

执行编译：

protoc --proto_path=proto \
  --go_out=. --go_opt=paths=source_relative \
  --go-grpc_out=. --go-grpc_opt=paths=source_relative \
  proto/hello/v1/hello.proto

成功后在 gen/hello/v1/ 目录下应生成 hello.pb.go 和 hello_grpc.pb.go 两个文件。如果遇到 protoc-gen-go-grpc: program not found，说明 $GOPATH/bin 未加入 PATH。

2.6 常见安装问题与排查清单