grpc-gateway http路由不生效的主因是未调用registerxxxhandlerserver将grpc服务注册到runtime.servemux，导致路由表为空而返回404；需确保protoc插件链完整、注解正确且生成代码被导入。
gRPC-Gateway 生成的 HTTP 路由不生效？检查 runtime.NewServeMux 是否被正确注入
gRPC-Gateway 不是自动监听 HTTP 端口的“服务”，它只是一个反向代理：把 HTTP 请求翻译成 gRPC 调用。你必须显式创建 runtime.ServeMux，并用它注册 gRPC 服务的 HTTP 映射规则，再把它挂到 HTTP server 上。
常见错误是只调用了 runtime.NewServeMux() 却没调用 RegisterXXXHandlerServer（注意后缀是 Server，不是 Client），导致路由表为空，所有请求 404。
- 确保在初始化
runtime.ServeMux后，调用由protoc-gen-grpc-gateway生成的注册函数，例如pb.RegisterUserServiceHandlerServer(ctx, mux, grpcServer) - 不要混用
HandlerClient—— 那是给客户端发请求用的，和 HTTP 服务无关 -
runtime.ServeMux默认不处理 OPTIONS 或 CORS；如需预检支持，得自己加中间件或用runtime.WithForwardResponseOption注入头
Protobuf 中的 google.api.http 注解没被识别？确认 protoc 插件链完整且版本对齐
gRPC-Gateway 的路由完全依赖 google.api.http 在 .proto 文件里的声明，但这个注解本身不会自动生效——它需要 protoc-gen-openapiv2 和 protoc-gen-grpc-gateway 两个插件协同解析。任意一环缺失或版本不匹配，都会导致生成代码里没有 RegisterXXXHandlerServer 函数，或 HTTP 路径硬编码为 /v1/xxx。
统一LLM网关 - 一个API对接70+AI模型，使用单一API密钥即可调用GPT、Claude、Gemini、Qwen、Deepseek、Grok等主流模型。
- 检查
go get安装的插件是否来自同一发布周期，例如grpc-gateway/v2@v2.15.2对应protoc-gen-grpc-gateway@v2.15.2 - 运行
protoc时必须同时指定--grpc-gateway_out和--go_out，且两者都指向同一import_path，否则生成的 Go 包无法互相引用 - 如果用了
body: "*"，确保对应 gRPC 方法的 request message 字段名与 JSON key 一致（默认 snake_case → camelCase 转换由runtime.WithMarshalerOption控制）
HTTP 请求能转发但响应体是空或格式错乱？排查 JSONPb 序列化配置与 gRPC 返回值结构
gRPC-Gateway 默认用 runtime.JSONPb 序列化响应，但它对嵌套结构、oneof、空字段、时间戳等处理较严格。常见现象是返回 {} 或字段全丢失，实际是 marshal 失败后静默跳过。
- 在
runtime.NewServeMux初始化时显式传入runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.JSONPb{OrigName: true, EmitDefaults: true})，避免字段名被重写或默认值被忽略 - 如果 gRPC handler 返回了
nilerror 但 response 结构体未初始化（比如只 new 了 struct 没赋值字段），JSONPb 可能序列化出空对象；建议用proto.Clone或构造器函数确保字段安全 - 时间字段推荐用
google.protobuf.Timestamp，避免自定义 time.Time 字段——后者需额外注册runtime.Marshaler才能正确转 JSON
如何让 gRPC-Gateway 和 gRPC Server 共享同一端口？用 grpc.Server 的 UnknownServiceHandler 做协议分发
生产环境通常要求单端口复用 HTTP/1.1 和 gRPC（HTTP/2），不能开两个监听地址。gRPC-Gateway 本身不支持 HTTP/2，所以必须靠 gRPC server 拦截非 gRPC 流量，再交给 Gateway 处理。
- 启用
grpc.UnknownServiceHandler，判断http.Request.ProtoMajor或Content-Type是否为application/grpc，否则交由runtime.ServeMux.ServeHTTP - 注意 TLS 配置：若用 HTTPS，gRPC client 必须设
WithTransportCredentials(credentials.NewTLS(...))，而 Gateway 的 HTTP client 也要用同源证书信任链 - 这种模式下，
runtime.ServeMux不能直接绑定http.ListenAndServe，否则会和 gRPC server 冲突；所有 HTTP 流量必须经由 gRPC server 的UnknownServiceHandler分流
最易被忽略的是错误传播：gRPC-Gateway 的 4xx/5xx 错误默认转成 gRPC status.Code，但前端看到的是 HTTP 状态码；如果你在 UnknownServiceHandler 里没正确透传 http.Error 或设置 ResponseWriter.WriteHeader，客户端可能收不到预期状态码。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
