Go gRPC开发核心是两步：用protoc生成代码（需安装protoc-gen-go和protoc-gen-go-grpc插件并配置PATH）和用grpc.Server/grpc.Dial启服务与调用；常见问题集中于插件缺失、TLS/超时配置错误、注册遗漏及拦截器签名不匹配。
Go 语言里写 gRPC 服务端和客户端，核心就两步：用 protoc 生成 Go 代码，再用 grpc.Server 和 grpc.Dial 分别启动服务与发起调用。不写好 .proto 文件、不装对插件、不处理好 TLS 或超时，90% 的“连不上”“panic”“context deadline exceeded” 都会在这几步卡住。
怎么用 protoc 生成 Go 的 gRPC 代码
很多人卡在第一步：protoc 跑出错，提示 “plugin not found” 或生成的文件里没有 XXXClient。这是因为 Go 的 gRPC 代码生成依赖两个插件：protoc-gen-go（基础 protobuf）和 protoc-gen-go-grpc（gRPC 接口）。它们不是内置的，得手动安装：
go install google.golang.org/protobuf/cmd/protoc-gen-go@latestgo install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
然后确保 $GOBIN（或 $GOPATH/bin）在系统 PATH 里。生成命令要带两个 --plugin 参数：
protoc --go_out=. --go-grpc_out=. --go-grpc_opt=paths=source_relative \ --go_opt=paths=source_relative \ helloworld/helloworld.proto
注意：--go-grpc_opt=paths=source_relative 很关键，否则生成的 import 路径可能错位；如果 proto 文件有 package 声明，生成的 Go 包名默认和它一致，别手动改包名，否则 RegisterXXXServer 会找不到类型。
立即学习“go语言免费学习笔记（深入）”；
服务端启动时 panic: “failed to listen” 或 “address already in use”
典型错误是 listen tcp :50051: bind: address already in use，或者更隐蔽的 panic: runtime error: invalid memory address 来自 grpc.NewServer() 后没注册服务就启监听。常见原因：
- 端口被占用：用
lsof -i :50051（macOS/Linux）或netstat -ano | findstr :50051（Windows）查进程并 kill - 监听地址写成
"localhost:50051"：gRPC 默认只绑127.0.0.1，但某些网络环境（比如 Docker 容器间调用）需要"0.0.0.0:50051" - 忘记调用
helloworld.RegisterGreeterServer(srv, &server{})：注册必须在srv.Serve(lis)之前，否则客户端能连上但所有 RPC 返回UNIMPLEMENTED
建议加个健康检查路由或日志确认服务真起来了：
lis, err := net.Listen("tcp", ":50051")
if err != nil {
log.Fatal(err)
}
srv := grpc.NewServer()
helloworld.RegisterGreeterServer(srv, &server{})
log.Println("gRPC server listening on :50051")
if err := srv.Serve(lis); err != nil {
log.Fatal(err)
}客户端 Dial 失败：context deadline exceeded 或 connection refused
最常见的不是代码写错，而是网络或配置问题。Dial 默认不带任何选项，等同于 grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials())) —— 注意这个 insecure.NewCredentials() 是必须显式加的，否则 Go 1.19+ 会直接拒绝明文连接。
- 如果服务端开了 TLS，客户端必须用
grpc.WithTransportCredentials(credentials.NewTLS(...))，不能漏掉WithTransportCredentials - 超时控制别只靠
context.WithTimeout包整个 RPC 调用，应该在Dial时加grpc.WithBlock()+grpc.WithTimeout(3 * time.Second)，避免 Dial 异步返回后立刻调用导致ClientConn is closing - Dial 字符串别写成
http://localhost:50051：gRPC 不走 HTTP 协议前缀，纯地址即可，如"localhost:50051"
一个健壮的 Dial 示例：
conn, err := grpc.Dial("localhost:50051",
grpc.WithTransportCredentials(insecure.NewCredentials()),
grpc.WithBlock(),
grpc.WithTimeout(5*time.Second),
)
if err != nil {
log.Fatal("did not connect:", err)
}
defer conn.Close()
client := helloworld.NewGreeterClient(conn)为什么简单示例跑得通，一加中间件就报错
很多教程跳过拦截器（interceptor）的初始化细节，结果加上 grpc.UnaryInterceptor 就 panic：“invalid interceptor”。根本原因是：拦截器函数签名必须严格匹配 func(ctx context.Context, req interface{}, info *UnaryServerInfo, handler UnaryHandler) (resp interface{}, err error)，少一个参数、类型不对、返回值顺序错都会崩溃。
- 日志拦截器里别直接
fmt.Println(req)：req是 interface{}，打印出来是地址，要用spew.Dump(req)或转具体类型 - 客户端拦截器返回
handler(ctx, req)前，务必确保ctx没被 cancel，否则下游直接CANCELLED - 多个拦截器串联时，顺序很重要：先注册的先执行（服务端），后注册的外层（客户端），别把认证拦截器放在日志之后还试图读 header
真正上线时，TLS、流控、链路追踪、重试策略这些不是“可选”，而是从第一个 protoc 命令就得规划好 option go_package 路径和模块版本，否则后期重构成本远高于初期多花十分钟配好 go.mod 和 buf.yaml。
