gRPC-Gateway是独立HTTP服务，需显式生成handler、连接运行中的gRPC后端并单独启动；必须在proto中声明google.api.http注解、正确import依赖、字段名与路径占位符严格一致、调用RegisterXXXHandlerFromEndpoint注册路由，且gRPC server须先就绪。
不能直接“导出”——grpc-gateway 不是 gRPC server 的插件或中间件，它是一个独立的 HTTP 服务，必须显式生成 handler、连接运行中的 gRPC 后端、并单独启动。
proto 文件里必须写 google.api.http 注解，且 import 正确
注解不会自动生效，只在代码生成阶段被 protoc-gen-grpc-gateway 读取。漏掉 import "google/api/annotations.proto" 或 import "google/api/http.proto"，生成的 service.pb.gw.go 里就完全没有路由逻辑。
- 字段名和路径占位符必须完全一致：
get: "/v1/users/{id}"要求 message 中存在string id = 1;，大小写敏感，不能是user_id或嵌套在User子消息里 -
body: "*"表示整个 JSON body 映射到顶层 message；若写body: "user.name"，则只提取{"user": {"name": "x"}}中的name字段，其余静默丢弃 - 多段路径如
get: "/v1/{name=projects/*/topics/*}"需启用allow_repeated_fields参数，否则 protoc 会跳过该规则
生成和 import pb.gw.go 文件后，必须手动注册 handler
RegisterXXXHandlerFromEndpoint 是唯一入口，不调用它，mux 里一条路由都没有，所有请求 404。
- 不能塞进 Gin/Echo 的路由树，比如
r.POST("/xxx", gwMux.ServeHTTP)—— 这会让框架丢失 method/path 匹配，最终 fallback 到 404 - 必须用
http.ListenAndServe(":8080", gwMux)或http.Server{Handler: gwMux}直接启动 -
ctx参数不能是已 cancel 的 context（例如从context.WithTimeout创建后超时），否则注册失败且无日志提示
endpoint 必须指向可连通的、已运行的 gRPC server
RegisterXXXHandlerFromEndpoint 内部会用 grpc.Dial 连接后端，地址不可达 → 503 Service Unavailable。
以 CLI 为先的表单构建器，采用 BYOK 理念。通过JSON Schema 生成美观的 HTML 表单，使用您自己的 SMTP 服务器处理提交，存储响应...
- 本地开发常用
"localhost:9090"，但 Docker 部署时需改成容器名（如"grpc-server:9090"）或宿主机 IP（"host.docker.internal:9090"） - gRPC server 必须先启动、监听成功，再初始化 gateway mux；顺序颠倒会导致 dial timeout
- 想共用 8080 端口同时响应 REST 和 gRPC？不能起两个
ListenAndServe，也不能让 gRPC server 直接Serve(lis)—— 正确做法是用h2c.NewHandler包裹 gRPC server 作为 fallback handler，主 handler 是 gateway mux
JSON 序列化行为容易导致字段丢失或类型不匹配
gateway 默认用 protojson 编解码，但零值字段（int32 status = 1; 值为 0）默认不输出，前端收不到该 key。
- 需显式配置
protojson.MarshalOptions{EmitUnpopulated: true}才能保留零值字段 - 时间字段
google.protobuf.Timestamp序列化为 RFC3339 字符串，但若 proto 中手写int64 seconds，gateway 不识别也不转换，会静默忽略 - 路径参数传
id: "123"，而 message 字段定义为int32 id→ 静默失败，返回 404；应统一用string id
最常被忽略的是：gateway 不是“自动代理”，它不感知 gRPC service 的存在，只依赖生成的 handler 和你填对的 endpoint 地址。哪怕 proto 写得再规范，只要 RegisterXXXHandlerFromEndpoint 没调、或 endpoint 不通、或 protojson 配置没开零值，接口就不可用。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
