echo不支持运行时动态注册路由，因路由树在e.start()后冻结；需用中间件拦截+自维护热更路由表（如sync.map+etcd watch）实现动态分发。
动态路由不能靠 Echo.Add() 运行时注册
很多人一上来就写 e.Add("GET", "/api/user", handler) 想热更新路由，结果请求 404 —— Echo 的路由树在 e.Start() 后就冻结了，运行时调用 Add、GET 或 Route() 全部静默失败，既不报错也不生效。这不是 bug，是设计使然：Echo 为性能把路由编译成静态 trie，不支持运行时插入。
真正能走通的路径只有一条：绕过 Echo 原生路由，用中间件拦截所有请求（比如 e.Any("/*path", dynamicRouter)），再查你自己的可热更路由表做转发。
- 别在中间件里每次请求都
client.Get()查 etcd —— QPS 上千时 etcd 成瓶颈，且网络延迟直接拖慢响应 - 别用普通
map[string]RouteRule+sync.RWMutex—— 写锁会阻塞高并发读，实测 QPS > 2k 时 p99 延迟翻倍 - 必须用
sync.Map存前缀级规则（如/api/user→http://user-svc:8080），更新时原子替换整个实例，读完全无锁
clientv3.Watch() 必须带 WithPrefix() 和 WithPrevKV()
监听路径写成 /routes/api 却收不到 /routes/api/v1/users 的变更？那是没加 clientv3.WithPrefix()。etcd 不会自动补斜杠或归一化路径，/routes/api 和 /routes/api/ 是两个完全不同的前缀。
WithPrevKV() 更关键：它让 DELETE 事件带上旧值，否则你分不清是服务主动下线，还是租约过期导致的 key 消失。没有它，每次 etcd compact revision 就得全量 reload，QPS 高时可能引发短暂 404。
- Watch 路径结尾统一加斜杠，例如
/routes/prod/ - 启动 Watch 前，先
client.Get(ctx, "/routes/prod/", clientv3.WithPrefix())拿初始 revision，再用clientv3.WithRev(rev + 1)启动，避免启动瞬间的变更丢失 - Watch 循环里必须检查
resp.Err()：遇到clientv3.ErrCompacted就用最新resp.Header.Revision + 1重建 watcher；遇到context.DeadlineExceeded就重试，不能直接 break
反向代理中间件要手动重写 Host 和 X-Real-IP
用 httputil.NewSingleHostReverseProxy() 转发时，目标服务看到的 Host 还是网关域名，RemoteAddr 是内网 IP —— 这会导致下游鉴权失败、日志 IP 错乱、甚至 HTTPS 重定向出错。
必须自己实现 Director 函数重写关键 header：
proxy := httputil.NewSingleHostReverseProxy(upstreamURL)
proxy.Director = func(req *http.Request) {
req.URL.Scheme = upstreamURL.Scheme
req.URL.Host = upstreamURL.Host
// 透传真实客户端 IP，优先取 X-Real-IP， fallback 到 RemoteAddr
if realIP := req.Header.Get("X-Real-IP"); realIP != "" {
req.Header.Set("X-Forwarded-For", realIP)
} else {
req.Header.Set("X-Forwarded-For", req.RemoteAddr)
}
req.Header.Set("X-Real-IP", req.Header.Get("X-Real-IP"))
req.Host = upstreamURL.Host // 强制覆盖 Host
}
-
c.Param()在动态代理中无效 —— 因为路由没走 Echo 的解析逻辑，路径参数得你自己从c.Request().URL.Path里截取或正则匹配 - 别在 Director 里做耗时操作（比如查 DB 或调外部 API），所有预处理必须在中间件主逻辑里完成，Director 只负责改 URL 和 header
- 如果上游服务依赖
Referer，记得显式保留：req.Header.Set("Referer", c.Request().Header.Get("Referer"))
etcd 连接初始化漏掉 grpc.WithBlock() 会卡死
直接 clientv3.New(clientv3.Config{Endpoints: []string{"..."} }) 启动服务，大概率卡在 main() 不往下走，或者 Watch 一启动就报 rpc error: code = Unavailable —— 这不是 etcd 挂了，而是 gRPC 连接没等就绪就返回了 nil 客户端。
必须显式加三项：
-
DialTimeout: 5 * time.Second—— 太短易被抖动误判，太长拖慢启动 -
DialOptions: []grpc.DialOption{grpc.WithBlock()}—— 让New()阻塞直到连接成功或超时，否则后续 Watch 全部失效 - 本地开发用
grpc.WithInsecure()；生产环境开 TLS 必须提供完整tls.Config，漏掉ServerName会报x509: certificate is valid for ... not ...
最常被忽略的是：Watch goroutine 必须独立启，不能塞进 HTTP server 启动流程里。它一旦卡住或 panic，整个服务就无法响应 readiness probe，K8s 会反复 kill restart。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
