grpc-gateway必须作为独立http服务启动且依赖grpc后端已就绪，否则返回404或503；proto中google.api.http注解仅在protoc生成阶段生效，需正确import annotations.proto和http.proto并启用grpc-gateway插件；registerxxxhandlerfromendpoint必须显式调用且不能塞入gin/echo路由树；路径参数名须与message字段名严格一致；docker部署时endpoint需用容器名而非localhost。
gRPC-Gateway 不是插件，也不是中间件，它必须作为独立 HTTP 服务启动，且依赖 gRPC 后端已就绪——否则所有请求返回 503 或 404。
proto 文件里 google.api.http 注解不生效？检查 import 和 protoc 插件链
注解本身在运行时完全无作用，只在 protoc 生成阶段被 protoc-gen-grpc-gateway 读取。漏掉以下任一 import，生成的 service.pb.gw.go 就不会包含任何路由逻辑：
import "google/api/annotations.proto"import "google/api/http.proto"
常见错误：只写 option (google.api.http) = { get: "/v1/users/{id}" }; 却没加 import；或把 http.proto 放错路径（比如没放在 $GOPATH/src/google/api/ 或没通过 -I 指定 include 路径）。
RegisterXXXHandlerFromEndpoint 调用失败或 404？别塞进 Gin/Echo 路由树
生成的 RegisterGreeterHandlerFromEndpoint 返回的是一个完整的 runtime.ServeMux 实例，它本身就是 http.Handler，不是中间件函数。
在 macOS 上通过 LaunchAgent 安装、更新、运行和移除 OpenClaw Gateway Monitor + Gateway Watchdog。适用于用户请求一键部署监控的场景。
- ❌ 错误写法：
r.POST("/v1/hello", mux.ServeHTTP)—— Gin 会忽略 method/path 匹配，最终 fallback 到 404 - ✅ 正确写法：
http.ListenAndServe(":8080", mux)或http.Server{Handler: mux}.ListenAndServe() - ctx 参数不能是已 cancel 的 context（例如
context.WithTimeout(ctx, time.Second).Done()已触发），否则注册静默失败，无日志提示
启动后返回 503 Service Unavailable？endpoint 地址和 gRPC server 状态必须严格对齐
RegisterXXXHandlerFromEndpoint 内部会调用 grpc.Dial 连接后端，失败即返回 503，不是配置错误，而是运行时连接问题：
- gRPC server 必须先启动、监听成功（如
localhost:9090），再初始化 gateway mux；顺序颠倒 → dial timeout - Docker 部署时，
endpoint不能写localhost:9090，得换成容器名（grpc-server:9090）或宿主机别名（host.docker.internal:9090） - gRPC server 若只 bind
127.0.0.1:9090，而 gateway 容器尝试连localhost，实际连的是自己，而非 host 上的服务
想共用 8080 端口同时响应 REST 和 gRPC？不能起两个 ListenAndServe
同一端口上同时暴露 REST 和 gRPC，不是靠“复用 listener”，而是靠 HTTP/2 + h2c 分流：
- 禁止：
go http.ListenAndServe(":8080", restMux)+grpcServer.Serve(lis)—— socket 抢占导致随机断连 - 正确做法：用
golang.org/x/net/http2/h2c.NewHandler(grpcServer, &http2.Server{})包裹 gRPC server 作为 fallback handler，主 handler 是 gateway mux - 这样所有非匹配 REST 路径的请求（比如
POST /helloworld.SayHello）自动降级到 gRPC 二进制协议
最容易被忽略的点：路径参数 {id} 对应的字段必须明确定义在 request message 中，且名字、类型、大小写完全一致；body: "*" 表示整个 JSON 映射到顶层 message，但若写成 body: "user.name"，字段缺失时 gateway 静默丢弃，不报错也不 warn。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
