gRPC服务定义必须用proto3且严格匹配Go结构体字段；连接需全局复用；超时由客户端context控制；流式响应须检查ctx.Err()并判断Send()错误；HTTP与gRPC应分端口部署。
gRPC服务定义必须用proto3且严格匹配Go结构体字段
gRPC通信效率高度依赖Protocol Buffers的序列化性能，而Go端生成代码能否正确映射，关键在于.proto文件定义与Go运行时结构的一致性。常见错误是手动修改pb.go文件或忽略json_name选项，导致HTTP/JSON网关或调试工具解析失败。
实操建议：
- 始终使用
syntax = "proto3";，避免proto2的默认值语义干扰 - 所有message字段名用
snake_case，并显式指定json_name以对齐Go结构体的json标签（如string user_id = 1 [json_name = "user_id"];） - 重复字段（
repeated）对应Go切片，但需注意空切片与nil切片在序列化行为上的差异——gRPC默认不发送nil切片，建议初始化为空切片 - 服务方法必须声明
rpc MethodName(Request) returns (Response);，不能省略returns子句
客户端连接复用和拦截器要主动管理生命周期
频繁创建*grpc.ClientConn会触发大量TCP握手与TLS协商，显著拖慢吞吐。Go的grpc.Dial返回的连接对象本身是线程安全、可并发复用的，但开发者常误以为每次调用都要新建连接。
实操建议：
- 全局复用单个
*grpc.ClientConn，通过WithBlock()控制阻塞行为，生产环境建议设为false并配合健康检查 - 超时必须由客户端控制：在
context.WithTimeout中设置，而非依赖服务端配置；gRPC不会自动传播HTTP-style timeout header - 日志、认证、重试等通用逻辑应封装为
grpc.UnaryClientInterceptor，但注意拦截器函数内不可panic，否则会中断整个调用链 - 连接关闭需显式调用
conn.Close()，尤其在微服务退出阶段，避免goroutine泄漏
服务端流式响应需小心处理context取消和缓冲区溢出
使用stream.Send()推送大量数据时，若客户端消费慢或网络卡顿，gRPC内部发送缓冲区会堆积，最终触发context.DeadlineExceeded或transport: failed to write a frame错误。
实操建议：
- 服务端流式方法的
ServerStream参数自带Context()，必须持续检查ctx.Err() != nil，一旦收到cancel或deadline，立即退出循环 - 避免在
for循环中无节制Send()，应在每次调用后加if err := stream.Send(msg); err != nil { return err }判断 - 如需背压控制，可在发送前调用
stream.SetHeader()传递元数据，或改用双向流（stream.Recv()确认客户端就绪） - 不要在流式Handler里启动长时间goroutine，其生命周期不受gRPC框架管理，易造成资源泄漏
Go微服务中gRPC与HTTP共存时的端口和路由冲突
很多团队用grpc-gateway提供REST+gRPC双协议，但常因监听端口、TLS配置、中间件顺序导致gRPC请求被HTTP路由器拦截，或HTTP fallback返回503 Service Unavailable。
实操建议：
- gRPC必须走纯TCP监听（
http.ListenAndServe不支持），推荐用grpc.NewServer()单独绑定:9000，HTTP/REST gateway另起:8080 - 若强制共用端口（如用
gRPC over HTTP/2+HTTP/1.1），需用net/http.Server的Handler做协议嗅探，但复杂度高、调试困难，不推荐 -
grpc-gateway生成的HTTP handler必须注册在http.ServeMux根路径（/），否则gRPC反射和健康检查接口（如/healthz）会404 - 启用gRPC健康检查服务（
grpc_health_v1.RegisterHealthServer）后，务必在gateway中配置runtime.WithHealthCheck，否则前端LB无法感知实例状态
func main() {
lis, _ := net.Listen("tcp", ":9000")
grpcServer := grpc.NewServer(
grpc.ChainUnaryInterceptor(authInterceptor, loggingInterceptor),
)
pb.RegisterUserServiceServer(grpcServer, &userService{})
// 启动gRPC服务
go func() {
log.Println("gRPC server listening on :9000")
grpcServer.Serve(lis)
}()
// 同时启动HTTP gateway
gwmux := runtime.NewServeMux()
err := pb.RegisterUserServiceHandlerFromEndpoint(context.Background(), gwmux, "localhost:9000", []grpc.DialOption{grpc.WithInsecure()})
if err != nil {
log.Fatal(err)
}
httpServer := &http.Server{Addr: ":8080", Handler: gwmux}
log.Println("HTTP gateway listening on :8080")
httpServer.ListenAndServe()
}
gRPC高效性的核心不在协议本身，而在你是否让Go的并发模型与gRPC的流控机制对齐——连接别乱建、context别漏判、流别硬推、端口别混用。这些点看似琐碎，但线上抖动往往就卡在其中某一个。 
