必须显式生成并启动独立http handler，grpc-gateway是反向代理而非协议转换中间件；proto中google.api.http注解仅在protoc阶段被读取生成路由代码，需正确import依赖；路径/查询参数须在request message明确定义；service.pb.gw.go返回runtime.servemux，须直接用http.listenandserve启动；grpc server需启用reflection且endpoint必须真实可连通；业务逻辑复用靠结构体共享+手动适配，错误需转为status.error；流式接口需手动配置marshaler；鉴权等中间件需额外封装，框架不自动支持。
不能靠框架“自动集成”gRPC网关，必须显式生成并启动独立的 HTTP handler；grpc-gateway 本质是反向代理，不是协议转换中间件。
proto 文件里 google.api.http 注解不生效？检查 imports 和 protoc 插件链
注解 option (google.api.http) 只是静态声明，运行时完全不参与逻辑。它只在 protoc 执行阶段被 protoc-gen-grpc-gateway 读取，用于生成 service.pb.gw.go 中的路由绑定代码。
- 必须显式
import "google/api/annotations.proto"和import "google/api/http.proto"，否则 protoc 直接忽略注解或报错 -
body: "*"表示整个 JSON body 映射到 message 字段；若写成body: "user.name"，gateway 会尝试从 JSON 路径提取，但字段缺失时静默丢弃，不报错 - 路径参数（如
{id}）和 query 参数（如?page=1）对应字段，必须在 request message 中明确定义，否则 gateway 不解析、不传入
生成的 service.pb.gw.go 没注册到路由？别塞进 Gin/Echo 的 handler 树
service.pb.gw.go 里生成的 RegisterGreeterHandlerFromEndpoint 函数，返回的是一个 runtime.ServeMux 实例——它是独立的 HTTP handler，不是中间件，也不能当子路由挂载。
- 禁止写成
r.GET("/v1/hello/{name}", mux.ServeHTTP)或类似 Gin/Echo 风格的注册，会导致 method/path 匹配失效，所有请求 fallback 到 404 - 必须用
http.ListenAndServe(":8080", mux)直接启动，或封装为http.Server{Handler: mux} - 如果要用单端口同时支持 REST 和 gRPC，得用
golang.org/x/net/http2/h2c.NewHandler包裹 gRPC server 作为 fallback handler，主 handler 是 gateway mux
启动后 503 或连接拒绝？endpoint 地址和 gRPC server 状态要严格对齐
RegisterXXXHandlerFromEndpoint 的 endpoint 参数不是配置项，而是运行时真实可连通的 gRPC server 地址（如 "localhost:9090"），且必须满足：
- gRPC server 已启动并监听该地址，不能是未解析域名、防火墙拦截端口或仅 bind 了
127.0.0.1却从容器外访问 - 传入的
context.Context不能是已 cancel 的（比如context.WithTimeout(ctx, time.Second).Done()后再传入），否则注册失败且无日志提示 - gRPC server 必须启用 reflection（
reflection.Register(server)），否则 gateway 在调试模式下无法获取服务元信息
想复用业务逻辑又避免双写？别指望框架自动桥接，得靠结构体共用 + 手动适配
grpc-gateway 不提供“自动调用业务函数”的能力。它只负责：HTTP → protobuf 解析 → 本地 gRPC client 调用 → protobuf → JSON 编码。中间的业务逻辑仍由你实现的 gRPC server 处理。
- request/response 结构体可以复用（比如定义在
types/下，被 proto 和业务层共同 import），但字段命名、tag、校验逻辑需保持一致 - 若业务层用的是自定义 error 类型（如
errors.New("not found")），需在 gRPC server 中转为标准status.Error(codes.NotFound, ...)，否则 gateway 无法映射为 404 - 流式接口（server-streaming）在 gateway 中默认不支持分块传输，需手动设置
runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.JSONPb{OrigName: false})并确认客户端接受 chunked response
最容易被忽略的一点：gateway 生成的 handler 不做任何中间件逻辑（鉴权、日志、trace 注入），这些都得在 gRPC server 层或 gateway mux 前加一层 wrapper，而不是寄希望于“框架集成”自动完成。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
