能跑通grpc服务核心是三件事：protoc代码生成正确、服务端注册不遗漏、客户端地址与tls配置匹配；其余均为优化项。
能跑通的gRPC服务，核心就三件事：protoc生成代码不出错、服务端注册不漏掉RegisterXXXServer、客户端连接地址和TLS配置对得上。其他都是锦上添花。
protoc生成Go代码时常见失败点
90%的“找不到包”“未定义类型”错误，都出在protoc命令参数或go_package配置上。
-
go_package必须写全路径，比如option go_package = "github.com/yourorg/project/api/user";，不能只写./user——否则生成的.pb.go文件里import路径错，编译直接报cannot find package -
protoc命令要同时指定--go_out和--go-grpc_out，缺一不可；且两个插件的paths=source_relative必须一致，否则生成路径混乱 - 插件二进制文件（
protoc-gen-go、protoc-gen-go-grpc）必须在$PATH里，运行which protoc-gen-go确认存在；Go 1.21+建议用@latest安装，避免版本不匹配
服务端启动后没响应？检查Listen和Register两步
服务起来但grpcurl连不上，大概率是监听地址绑定或服务注册漏了。
- 监听地址别写
localhost:50051——这只会绑定到IPv4回环，外部容器或宿主机访问失败；改用0.0.0.0:50051或[::]:50051 - 生成的
RegisterXXXServer函数必须显式调用，比如pb.RegisterUserServiceServer(grpcServer, &userService{})；Goravel等框架会自动做，但原生Go必须手写 - 如果用了拦截器（如认证、日志），确保
grpc.UnaryInterceptor传入的是函数，不是字符串名；Goravel里interceptors配置项是字符串数组，但底层仍需对应函数注册
客户端连不上服务？优先验证网络层和TLS设置
错误信息像connection refused或transport: authentication handshake failed，基本和业务逻辑无关。
- 先用
telnet host port或nc -zv host port确认TCP层通不通；不通就查防火墙、Docker network、K8s Service配置 - 默认gRPC客户端强制启用TLS，若服务端没配证书，必须加
grpc.WithTransportCredentials(insecure.NewCredentials())；Go 1.22+已弃用grpc.WithInsecure()，别抄旧教程 - 服务发现场景下，客户端
host:port填的是注册中心地址（如etcd），不是直连后端地址——这时需要额外集成resolver，不是简单改字符串就能解决
性能卡在QPS上？先看连接复用和超时配置
本地压测QPS上不去，往往不是代码问题，而是gRPC默认配置太保守。
- 客户端别每次调用都
grpc.Dial——连接创建开销大；应全局复用一个*grpc.ClientConn，它本身是线程安全的 - 服务端默认没有设置
MaxConcurrentStreams，高并发下可能被HTTP/2流数限制卡住；建议显式设为1000或更高 - 所有RPC调用必须带context超时，比如
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)；否则失败请求会堆积，拖垮整个连接
真正难的不是写完第一个SayHello，而是让服务在K8s里稳定跑一周不OOM、不丢请求、不因证书过期突然中断——这些细节藏在grpc.ServerOption和grpc.DialOption的参数组合里，而不是.proto文件里。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
