gRPC Server 不能直接集成到 Martini/Gin/Echo 等 HTTP 框架中，因其依赖 HTTP/2 及特定 preface 帧，而 HTTP 框架仅支持 HTTP/1.1；必须单独监听 TCP 端口，并正确注册服务与生成代码。
gRPC Server 不能塞进 Martini/Gin/Echo 等 HTTP 框架
直接把 grpc.Server 注册进 Martini 或挂到 Gin 的路由树里，必然失败。HTTP 框架只处理 HTTP/1.1 请求，而 gRPC 必须走 HTTP/2 并依赖特定 preface 帧（PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n），框架根本无法识别或转发。
常见错误现象包括：connection closed before server preface received、rpc error: code = Unavailable desc = transport is closing、用 curl 访问 gRPC 端点返回 404 Not Found。
- 必须用
net.Listen("tcp", ":50051")单独启动监听，不要加http://前缀 -
grpc.NewServer()后必须调用pb.RegisterXXXServer(s, &impl{})，否则客户端连得上但所有 RPC 返回UNIMPLEMENTED - 若需共用端口提供 REST + gRPC，应由反向代理（如 Nginx/Envoy）按 ALPN 或路径分流，而非在 Go 应用层混搭
proto 文件生成失败的三个高频原因
90% 的编译失败或运行时 panic 来自生成环节，不是代码逻辑问题。
protoc 需要两个插件协同工作：protoc-gen-go（生成消息结构）和 protoc-gen-go-grpc（生成服务接口）。缺一不可。
立即学习“go语言免费学习笔记（深入）”；
- 插件未安装或不在
$PATH：执行go install google.golang.org/protobuf/cmd/protoc-gen-go@latest和go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest，确认$GOBIN已加入环境变量 - 生成命令漏掉
--go-grpc_opt=paths=source_relative：否则生成的 import 路径错乱，RegisterXXXServer找不到类型 -
go_package声明与实际目录结构不一致：例如option go_package = "./user";，就要求生成文件放在./user目录下，不能手动挪动或改包名
grpc-gateway 不是中间件，必须独立启动 HTTP handler
grpc-gateway 是反向代理，不是协议转换中间件。它不嵌入 Gin/Echo，也不能当子路由注册。
google.api.http 注解只在 protoc 阶段被读取，用于生成 service.pb.gw.go 中的路由绑定代码。运行时完全不参与逻辑。
- 必须显式调用
runtime.NewServeMux()，再通过RegisterXXXHandlerFromEndpoint(ctx, mux, "localhost:50051", ...)绑定 gRPC 后端地址 - 启动必须用
http.ListenAndServe(":8080", mux)，不能塞进r.GET("/v1/xxx", mux.ServeHTTP)这类框架路由 - 路径参数（如
{id}）和 query 参数（如?page=1）对应字段，必须在 request message 中明确定义，否则 gateway 不解析、不传入
单端口共存 REST/gRPC 的真实可行路径
想用一个端口同时响应 HTTP/1.1 和 HTTP/2 请求，唯一可靠方式是用 golang.org/x/net/http2/h2c 包做 fallback。
主 handler 是 grpc-gateway 的 runtime.ServeMux，gRPC server 作为 fallback handler 接收未匹配的 HTTP/2 流量。
- 不能依赖框架自动识别协议——Gin/Echo 无 HTTP/2 支持能力，Martini 更无
-
h2c.NewHandler(mux, s.GRPCServer())中的s.GRPCServer()必须是已启动的、可连通的实例，否则 gateway 初始化时会报503 Service Unavailable - 容器部署时注意：Docker 默认不透传 HTTP/2，需确保宿主机或 ingress controller 支持 ALPN 协商
真正难的不是“怎么写”，而是守住边界：gRPC 是独立协议栈，强行缝合 HTTP 框架只会掩盖问题，让错误更难定位。每次看到有人在 main.go 里试图把 grpc.Server 塞进 martini.Classic()，基本就能预判后续三天都在查 transport is closing。
