需安装protoc-gen-go和protoc-gen-go-grpc插件并加入path，go 1.24+推荐用go install命令安装；服务注册须在grpc.newserver()后、s.serve()前完成且传指针；dial失败先检查端口监听状态；错误应使用status.errorf返回并用status.convert解包。
protoc 生成 Go 代码时 missing plugin 错误怎么修
常见现象是执行 protoc --go_out=. --go-grpc_out=. service.proto 时提示 protoc-gen-go: program not found or is not executable 或类似 plugin missing 报错。根本原因不是 protoc 本身没装好，而是两个 Go 插件没装、没在 PATH 里，或者版本不匹配。
- 必须分别安装
protoc-gen-go和protoc-gen-go-grpc，缺一不可；仅装protoc-gen-go会导致--go-grpc_out失效 - Go 1.24+ 环境下，推荐用
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest和go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest，避免用旧版grpc-go的 deprecated 插件 - 安装后检查
$(go env GOPATH)/bin是否已加入系统 PATH；macOS/Linux 可运行echo $PATH | grep -q "$(go env GOPATH)/bin"快速验证 - 如果项目用了 Go modules，确保
go.mod中已声明google.golang.org/grpc和google.golang.org/protobuf依赖，否则生成的代码可能编译失败
服务注册时 RegisterXXXServer 未生效的典型原因
启动服务后客户端连不上、报 UNIMPLEMENTED 或直接连接拒绝，大概率是服务没真正注册成功——不是代码写错了，而是调用时机或对象生命周期出了问题。
-
pb.RegisterUserServiceServer(s, &server{})必须在grpc.NewServer()之后、s.Serve(lis)之前调用；放在main函数末尾但漏掉这行，服务就等于没暴露任何方法 -
&server{}要传指针，传值（server{}）会导致方法接收者为值类型，无法满足pb.UserServiceServer接口（gRPC 生成代码要求指针接收者） - 如果 server 结构体嵌套了其他字段且未导出（小写开头），可能导致某些拦截器或反射逻辑异常，但更常见的是编译不报错、运行时静默失败
- 确认
lis, err := net.Listen("tcp", ":50051")成功，端口被占用时err非 nil，但若没做if err != nil { log.Fatal(err) }，程序会 panic 或提前退出
客户端 Dial 失败：timeout / connection refused 怎么快速定位
错误信息看起来像网络问题，但多数情况其实是服务端根本没起来，或监听地址不对。别急着查防火墙，先本地验证最简路径。
- 用
netstat -tuln | grep 50051（Linux/macOS）或netstat -ano | findstr :50051（Windows）确认端口是否真在 LISTEN 状态；没输出 = 服务没跑起来或监听了别的地址（比如127.0.0.1:50051而非:50051） - 客户端
grpc.Dial("localhost:50051", ...)中的 host 必须和服务端net.Listen的地址一致；若服务端监听0.0.0.0:50051，客户端用localhost没问题；但若服务端监听127.0.0.1:50051，某些容器环境里localhost可能解析失败 - 加一个简单的健康检查：服务端启动后，用
curl -v http://localhost:50051会返回 gRPC 的 HTTP/2 preface 错误（如 “PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n”），这说明端口通、HTTP/2 服务已就绪；返回 connection refused 就说明服务根本没 bind - 临时关闭客户端的超时设置：
grpc.WithTimeout(30 * time.Second)改成grpc.WithBlock()+ 更长 timeout，排除因服务启动慢导致的误判
Unary RPC 返回 error 但客户端收不到具体信息
服务端写了 return nil, fmt.Errorf("user not found")，客户端却只看到 rpc error: code = Unknown desc = error sending request ——这不是 bug，是 gRPC 默认把 error 映射成通用状态码，原始消息被吞了。
- 要用
status.Errorf替代fmt.Errorf：例如return nil, status.Errorf(codes.NotFound, "user %d not found", req.Id)，这样客户端才能拿到准确的codes.NotFound和可读描述 - 客户端需用
status.Convert(err)解包：直接打印err.Error()只能看到摘要，要获取详细 code 和 message 得这么写：st := status.Convert(err); fmt.Println(st.Code(), st.Message()) - 自定义错误详情（如 trace ID、业务码）可通过
status.WithDetails附加*myerror.ErrorDetail类型结构体，但需确保 client 和 server 都引用同一 proto 定义并生成对应代码 - 注意：
codes.Internal和codes.Unknown在生产环境应尽量避免直接返回，它们常掩盖真实问题，调试时难定位
实际跑通一个 gRPC 流程，最难的往往不是写代码，而是确认那几个看似无关紧要的路径、插件版本、地址绑定和错误包装方式——它们不报语法错，但会让整个调用链静默断裂。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
