直接用protoc生成的Go代码无法直接跑通生产环境，必须配置拦截器、超时、流式错误处理；proto中go_package路径须与目录结构一致，否则编译报cannot find package；protoc命令需加paths=source_relative避免硬编码路径；服务端必须正确注册实现类并嵌入UnimplementedXXXServer；客户端调用必须显式设置context.WithTimeout。
直接用 protoc 生成的 Go 代码就能跑通基础通信，但生产环境里不配拦截器、不设超时、不处理流式错误，服务一压就挂，调用方等不到响应就超时熔断——这不是 gRPC 不行，是没踩对关键配置点。
proto 文件里必须写 go_package 且路径要和实际目录一致
不写或写错 go_package，生成的 *_grpc.pb.go 里会 import 错包路径，编译直接报 cannot find package。常见错误现象是：go build 提示找不到 userpb 或类似模块名，但你明明在当前目录下执行了 protoc。
实操建议：
-
option go_package = "yourproject/api/userpb";—— 这个路径必须对应你最终存放*.pb.go文件的目录结构，比如生成文件在api/userpb/user.pb.go，那这里就得写成"yourproject/api/userpb" - 不要用相对路径（如
./userpb），protoc-gen-go从 v1.26+ 开始已弃用该写法 - 如果 proto 在
api/下，建议统一用模块名开头，例如github.com/you/project/api/userpb，避免本地开发和 CI 环境路径不一致
protoc 命令参数顺序和插件选项容易漏掉 paths=source_relative
不加 --go-grpc_opt=paths=source_relative，生成的 import 语句会硬编码绝对路径（比如 import _ "/home/xxx/api/user.pb.go"），换机器或进 Docker 就编译失败。
立即学习“go语言免费学习笔记（深入）”；
正确命令模板（Go 模块下）：
protoc \ --go_out=. \ --go_opt=paths=source_relative \ --go-grpc_out=. \ --go-grpc_opt=paths=source_relative \ api/user.proto
注意点：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
-
--go_opt和--go-grpc_opt必须分开写，不能合并成一个--go_opt=paths=source_relative,plugins=grpc（旧写法已废弃） - 所有
.proto文件路径必须是相对于protoc当前工作目录的，不是相对于api/目录本身 - 若 proto 引用了其他 proto（如
google/protobuf/timestamp.proto），需用-I显式指定include路径，否则报File not found
服务端启动时没注册实现类，RegisterXXXServer 调用被忽略
常见错误现象：服务端进程正常启动、监听端口，但客户端调用返回 rpc error: code = Unimplemented desc = ...。这是因为 RegisterXXXServer 没生效，或者传入的是 nil 实例。
典型陷阱：
- 忘记嵌入
UnimplementedXXXServer：如果你只实现了部分方法，又没嵌入UnimplementedUserServiceServer，未实现的方法会 panic，而不是返回Unimplemented - 注册时传了空 struct：
RegisterUserServiceServer(srv, &UserService{})，而UserService{}是空 struct，没有实现任何方法 - 用错了 server 类型：
grpc.NewServer()返回的是*grpc.Server，但RegisterXXXServer第一个参数必须是它，别误传成http.Server或自定义 wrapper
安全写法：
type userService struct {
pb.UnimplementedUserServiceServer
}
func (s *userService) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.GetUserResponse, error) {
return &pb.GetUserResponse{User: &pb.User{Id: req.UserId}}, nil
}
// 启动时
srv := grpc.NewServer()
pb.RegisterUserServiceServer(srv, &userService{})
lis, _ := net.Listen("tcp", ":8080")
srv.Serve(lis)
客户端调用不设 context.WithTimeout，请求永远卡住
gRPC 默认不设超时，一旦后端卡死、网络中断或服务崩溃，客户端会无限等待，goroutine 泄露，连接堆积。线上最常看到的现象是：QPS 没涨，但 net.Conn 数持续上升，最后 OOM。
必须显式控制：
- 每个 unary 调用前都套
context.WithTimeout(ctx, 5*time.Second)，别依赖全局 context - 流式调用（stream）更要小心：
ClientStream.SendMsg和RecvMsg都可能阻塞，得用带 cancel 的 context 控制生命周期 - 别把
context.Background()直接传给conn, err := grpc.Dial(...)—— 连接建立阶段也要超时，建议用grpc.WithBlock()+context.WithTimeout包裹 dial
最小安全调用模式：
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
resp, err := client.GetUser(ctx, &pb.GetUserRequest{UserId: "123"})
真正难的不是写出第一个 grpc.Server，而是让每个 UnaryInterceptor 都能拿到 trace ID，让每个流式连接在断连时自动重试，让 protoc 在 CI 里稳定输出——这些细节不在 hello world 示例里，但在每天上线前的十分钟里，决定服务到底稳不稳。
