Go gRPC 实践：协议生成、调用边界与调试

本轮只做理论正文与源码静态复核；下列命令、示例和测试均未执行。已有输出按代码推演或历史记录理解，不作为本轮运行证据。

前置：Protobuf 基础、Modules、context。先完成单机客户端与服务端，再引入注册发现和框架。

工具与版本

需要 protoc、protoc-gen-go、protoc-gen-go-grpc。先确定相互兼容的 Go、生成器和运行时库版本，并记录在工程工具说明里。以下为安装命令形式，执行时将版本占位符替换为项目选定值：

go install google.golang.org/protobuf/cmd/protoc-gen-go@<version>
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@<version>
protoc --version
protoc-gen-go --version
protoc-gen-go-grpc --version

确认 GOBIN 或 GOPATH/bin 在 PATH 中；protoc 本身不是通过 go install 安装的 Go 工具。

生成消息和服务

使用协议课的 hello.proto，模块名为 example.com/hello，在模块根运行：

protoc -I . --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=paths=source_relative api/hello.proto

预期生成 api/hello.pb.go 和 api/hello_grpc.pb.go。-I 是 proto 导入搜索根，paths=source_relative 控制输出路径；Go 导入路径由 go_package 等选项决定。旧的 --go_out=plugins=grpc 属于旧生成链路，不应与两个新插件的命令混用。

若提示无法确定 Go import path，检查 go_package 是否完整，与 go.mod 及目标目录是否一致；提示找不到插件时检查 PATH；依赖 .proto 找不到时检查 -I，不应直接修改生成文件或把临时本机路径写成团队公共配置。

服务端与客户端

服务端创建 listener 与 grpc.Server，注册生成的 GreeterServer 实现。生成接口若要求嵌入 UnimplementedGreeterServer，应按当前生成代码的要求实现；旧文章中的极简 server 不能直接跨版本照搬。客户端复用连接，调用时传入带 deadline 的 context，并检查返回状态。

服务方法的形状如下，这是依赖生成代码的实现片段：

func (s *server) SayHello(ctx context.Context, req *hellopb.HelloRequest) (*hellopb.HelloReply, error) {
    if req.GetName() == "" {
        return nil, status.Error(codes.InvalidArgument, "name is required")
    }
    return &hellopb.HelloReply{Message: "Hello " + req.GetName()}, nil
}

其中 hellopb 是生成包，status/codes 来自 google.golang.org/grpc。网络连接成功、服务注册成功与某次调用成功是不同阶段，错误应分别定位；生产通信的传输凭据与身份校验由服务部署方案决定。可运行的完整双端工程与连接 API 以 gRPC Go 官方快速开始 为基准。

grpcui 与描述符

命令行工具同样用显式版本的 go install 安装，例如 github.com/fullstorydev/grpcui/cmd/grpcui@<version>。若服务没有开放 reflection，可用 protoc 生成包含依赖的描述符集：

protoc -I . --descriptor_set_out=api.protoset --include_imports api/hello.proto
grpcui -bind 127.0.0.1 -port 8506 -plaintext -protoset api.protoset 127.0.0.1:50051

-plaintext 适用于本地明文练习，与生产 TLS 配置分开。不要把 0.0.0.0 当成客户端必须连接的服务地址。

练习与验收

本页是协议生成与接入参考，代码块为需要补充生成包及已选依赖的片段，不宣称完整双端工程。先在纸面核对同一模块的协议与生成路径，再推演正常姓名、空姓名、服务未启动和 deadline 四种结果。若引入服务发现，额外核对注册实例的可达地址、服务名、环境隔离与注销顺序，而不只检查注册页面出现一个实例。

调用案例与参考判断

假定SayHello使用上面的实现，name=Alice预期Hello Alice；name为空预期InvalidArgument且没有成功消息。服务不可达与请求期限耗尽不是一个结果：连接/重试策略和剩余deadline共同决定最终状态，不能硬断言“停服务一定立即Unavailable”。客户端应同时检查RPC错误、返回值和context状态。

提示：服务端正常返回前deadline已耗尽时，能否据客户端错误断言服务端未执行？

参考答案

不能。错误可能发生在执行前、处理中或响应传输阶段；写操作需要独立幂等合同。服务发现只提供候选地址，不保证本次RPC成功。生成路径检查不等于编译、网络或身份验证。