必须重写req.URL.Path和req.Host，否则90%的404和后端鉴权失败由此导致：req.URL.Path需TrimPrefix截掉网关前缀以匹配后端路径，req.Host需显式设为目标服务Host头，因二者无自动同步且后端依赖其做路由或鉴权。
直接用 gorilla/mux 或 chi 注册路由 + 转发，跑得通但扛不住生产流量；真要高性能、可维护的路由转发，核心不在选什么框架，而在怎么用 httputil.NewSingleHostReverseProxy 安全兜底、再用中间件补业务逻辑。
为什么 Director 函数里必须重写 req.URL.Path 和 req.Host
不改这两项，90% 的 404 和后端鉴权失败都由此而来。后端服务通常不认网关层的路径前缀（比如 /api/v1/users），只处理 /users；而 req.URL.Host 只影响请求 URL 的域名部分，实际发出的 HTTP Host 头仍为客户端原始值——很多服务靠 Host 做多租户路由或证书匹配，不覆盖就错。
必须在 Director 中显式写：
proxy.Director = func(req *http.Request) {
req.URL.Scheme = "http"
req.URL.Host = "user-service:3000"
req.URL.Path = strings.TrimPrefix(req.URL.Path, "/api/v1") // 前缀必须和路由配置完全一致
req.Host = "user-service:3000" // 这行不能少，它才是真正发出去的 Host 头
}
-
strings.TrimPrefix的第一个参数是原始请求路径，第二个是网关暴露的 API prefix，二者必须严格匹配，多一个斜杠或大小写错误都会导致截断失效 -
req.Host是独立字段，和req.URL.Host无自动同步关系，漏设等于把客户端 Host 直接透传给后端 - 如果后端是 Kubernetes Service，
req.Host应设为 Service FQDN（如user-service.default.svc.cluster.local），而非 IP
ErrorHandler 不设就会 panic 崩溃
httputil.NewSingleHostReverseProxy 默认把底层网络错误（DNS 解析失败、连接被拒、TLS 握手超时）原样抛出，不捕获就触发 goroutine panic，整个 HTTP server 会退出。这不是“异常”，而是设计如此——它只负责代理骨架，错误处置必须你来填。
立即学习“go语言免费学习笔记（深入）”；
最简健壮写法：
proxy.ErrorHandler = func(rw http.ResponseWriter, req *http.Request, err error) {
log.Printf("proxy to %s failed: %v", req.URL.Host, err)
http.Error(rw, "upstream unavailable", http.StatusServiceUnavailable)
}
- 别只打印日志就完事，一定要调用
http.Error或手动写 status+body，否则 client 会卡在 pending 状态 - 常见误判：把
net/http.ErrServerClosed当作上游错误捕获，其实它是服务关闭信号，不该进 ErrorHandler - 若需区分错误类型做降级（如 DNS 失败返回缓存，连接超时返回 503），得用
errors.As检查具体错误包装
超时和重试不能塞进 http.Transport 配置里
Transport 层只管连接建立、复用和单次读写，没法判断“这个 502 是因为下游重启还是瞬时过载”，更没法决定“要不要重放请求体”。重试必须由中间件在业务语义层控制。
推荐组合：
-
Timeout设为 5–8 秒：比下游 P99 延迟高 2 秒，避免误熔断，也防 goroutine 积压 -
IdleConnTimeout设为 30 秒：对齐主流后端 keep-alive 设置，防止连接池里大量 stale 连接 - 重试仅针对
502/503/504和net.ErrClosed、context.DeadlineExceeded，且最多 1 次 + jitter - 重试动作放在 Gin/chi 中间件里，用
c.Next()后检查c.Writer.Status()，再决定是否重放c.Request.Body
Transport 自己不重试，这是 Go HTTP 的明确设计约束，强行绕开只会让错误更难排查。
JWT 时间不同步会导致 90% 的 “token expired” 报错
不是密钥错了，也不是算法不匹配，而是网关服务器本地时间比 NTP 服务器慢了 2 秒以上。jwt-go 默认误差容忍仅 ±1 秒，exp 字段是绝对 Unix 时间戳，跨机房部署或压测时 drift 极易超标。
必须做两件事：
- 启用
systemd-timesyncd并调高同步频率：sudo systemctl edit systemd-timesyncd，加[Time] NTP=pool.ntp.org和FallbackNTP=169.254.169.123 - 解析 token 时显式放宽容错：
jwt.ParseWithClaims(tokenString, claims, keyFunc, jwt.WithValidMethods([]string{"RS256"}), jwt.WithLeeway(5))，leeway=5表示允许 5 秒偏差 - 别依赖
time.Now().Unix()做校验，用time.Now().UTC().Unix()避免时区干扰
所有这些细节加起来，才构成一个不会在凌晨三点把你叫醒的 Go 网关路由转发链。真正难的从来不是“怎么转”，而是“怎么不出错地转”。
