grpc-gateway需三步协同：protoc分两轮生成代码（先--go_out/--go-grpc_out，再--grpc-gateway_out）、google.api.http注解须与proto字段严格一致、registerxxxhandlerfromendpoint必须在http.listenandserve前调用，任一缺失均导致404或400。
gRPC-Gateway 不是“开个开关就能 HTTP”，它必须跑通三件事：protoc 分两轮生成代码、google.api.http 注解写得严丝合缝、RegisterXXXHandlerFromEndpoint 在 http.ListenAndServe 前调用——漏掉任何一环，接口就 404 或 400。
protoc 必须分两次执行，不能合并
很多人卡在第一步：用一条 protoc 命令同时加 --go_out、--go-grpc_out 和 --grpc-gateway_out，结果 your_service.pb.gw.go 是空文件，或报错 google/api/annotations.proto: File not found。
-
--go_out和--go-grpc_out负责解析 proto 语法、生成.pb.go和_grpc.pb.go；它们必须先跑，确保结构定义存在 -
--grpc-gateway_out只读取已生成的 Go 代码里的 service 定义，不参与 protobuf 解析；它必须后跑，且依赖third_party/googleapis路径 - 命令示例（注意
-I路径）：protoc -I . -I $GOPATH/pkg/mod/github.com/grpc-ecosystem/grpc-gateway@v2.15.2/third_party/googleapis/ --go_out=. --go-grpc_out=. your_service.protoprotoc -I . -I $GOPATH/pkg/mod/github.com/grpc-ecosystem/grpc-gateway@v2.15.2/third_party/googleapis/ --grpc-gateway_out=. --grpc-gateway_opt logtostderr=true your_service.proto
google.api.http 注解写错一个字符，HTTP 就 404
这个注解不是装饰，是路由和参数绑定的唯一依据。大小写、引号、字段名、路径占位符，全都要和 proto message 定义严格一致。
Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。
-
post: "/v1/users"要求body: "*"；漏写返回 400，不是 404 -
get: "/v1/users/{id}"要求 message 中存在string id = 1;；若字段是user_id却写成{id}，gateway 直接跳过该路由，返回 404 - query 参数如
get: "/v1/users?status={status}"，status必须是一级字段；UserFilter.status这类嵌套结构不支持自动展开 - 避免换行缩进写法：
option (google.api.http) = { post: "/v1/foo" };—— 某些旧版 protoc 会静默忽略整条注解
RegisterXXXHandlerFromEndpoint 必须在 ListenAndServe 前调用
生成的 .pb.gw.go 文件里只提供注册函数（比如 RegisterUserServiceHandlerFromEndpoint），它把反向代理 handler 挂载到 runtime.ServeMux 上。这个动作不可省略，也不可延迟。
- 不调用 →
http.ServeMux为空 → 所有请求 404 - 塞进 Gin/Echo 的路由树（例如
r.POST("/xxx", mux.ServeHTTP)）→ 框架丢失 method/path 匹配 → 全部 fallback 到 404 - 必须用
http.ListenAndServe(":8080", mux)或http.Server{Handler: mux}直接启动 -
ctx参数不能是已 cancel 的 context（例如从context.WithTimeout创建后超时了），否则注册失败且无任何提示
最常被忽略的是 endpoint 地址是否真实可达——RegisterXXXHandlerFromEndpoint 传入的 gRPC 地址（如 "127.0.0.1:9090"）必须和你实际运行的 gRPC server 绑定地址完全一致，Docker 或 IPv6 环境下 localhost 和 127.0.0.1 可能解析不同，导致 connection refused。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
