grpc-gateway 404 的根本原因是 protoc 未正确注入 google.api.http 扩展或生成的 pb.gw.go 文件未被导入；必须显式 import pb.gw.go、在 runtime.newservemux 上调用 registerxxxhandlerfromendpoint，并确保 proto 中正确声明 option (google.api.http)。
gRPC-Gateway 生成的 HTTP 路由为什么 404？
根本原因通常是 protoc 未正确注入 google.api.http 扩展，或生成的 xxx.pb.gw.go 文件没被导入。gRPC-Gateway 不会自动注册路由——它只生成 handler 函数，你得手动把它们挂到 HTTP mux 上。
- 检查 .proto 文件是否 import
"google/api/annotations.proto"，且每个 RPC 方法都有option (google.api.http) = { ... };声明 - 运行
protoc时必须带上--grpc-gateway_out参数，且路径指向已安装的protoc-gen-grpc-gateway - 生成的
*.pb.gw.go文件需在 main 包中显式 import（哪怕没直接调用），否则 Go linker 会丢弃该文件里的 init() 注册逻辑 - 确保用的是
runtime.NewServeMux()，不是http.ServeMux；后者不支持 gRPC-Gateway 的 path matching 规则
如何让 gRPC-Gateway 支持 PUT / PATCH / DELETE？
默认生成只处理 GET 和 POST，其他方法需显式声明。gRPC-Gateway 本身不转换 HTTP method，它依赖 google.api.http 中的 get/post/put/delete/patch 字段映射到对应 RPC 方法。
- 在 .proto 中为非 GET/POST 方法添加对应 option，例如：
option (google.api.http) = { put: "/v1/users/{id}" }; - 注意 path 中的字段名（如
{id}）必须与 RPC 请求 message 的字段名完全一致，且类型为 string 或 int32/64；否则 runtime 无法提取参数，返回 404 或 405 - PUT/PATCH 请求体默认反序列化到 request message，但若 body 是纯 JSON 对象而非嵌套在字段里，需加
body: "*"，否则报cannot unmarshal JSON array into proto field
如何透传原始请求头和响应头？
gRPC-Gateway 默认只转发部分 header（如 Content-Type、Authorization），自定义 header 需显式配置，否则下游 gRPC server 收不到。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 初始化
runtime.ServeMux时传入runtime.WithForwardResponseOption和runtime.WithIncomingHeaderMatcher - 用
runtime.HeaderMatcherFunc定义白名单，例如允许X-Request-ID、X-User-ID：返回true表示透传 - 响应头同理，用
runtime.WithForwardResponseOption+ 自定义函数，在resp.Header.Set()中写入 - 注意：gRPC metadata key 默认小写加横线（
x-request-id），但 HTTP header 名是大小写不敏感的；实际转发时建议统一用小写避免歧义
为什么 gRPC-Gateway 启动后 CPU 占用高？
常见原因是未设置合理的超时或未关闭 debug 日志，尤其在高并发场景下，JSON marshal/unmarshal 和反射路径匹配开销明显。
- 禁用
runtime.WithHealthzEndpoint（除非真需要健康检查端点），它默认每秒轮询一次 gRPC server - 用
runtime.WithTimeout(30 * time.Second)显式设 timeout，避免长连接堆积 - 避免在 handler 中做 heavy JSON decode —— 若请求体很大，考虑用 streaming 或分块上传
- 生产环境务必关掉
runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.JSONPb{OrigName: false, EmitDefaults: false})中的EmitDefaults: true，否则空字段全输出，增大 payload 和解析负担
最易被忽略的是 runtime.NewServeMux 的 options 初始化顺序：header matcher 必须在 mux 创建时传入，后续无法动态修改；而 response option 可以在 Handle 之前追加，但一旦注册就不可撤回。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
