真高性能API网关核心在于httputil.NewSingleHostReverseProxy的安全兜底与中间件协同：Director必须重写req.URL.Scheme、Host、Path以解决404与鉴权失败；Transport需自定义连接池，ErrorHandler重写JSON错误响应，ModifyResponse删除hop-by-hop头；路由用chi或gin替代ServeMux，鉴权与日志前置，WebSocket需单独拦截。
httputil.NewSingleHostReverseProxy 是起点，但直接用它跑生产环境等于埋雷。Go 语言没有开箱即用的 API 网关，必须手动补全关键环节，否则压测一上、流量一涨，连接耗尽、IP 透传错乱、HTTPS 跳转失败、错误响应格式不统一等问题会立刻暴露。
httputil.NewSingleHostReverseProxy 的三个必改字段
Director、Transport 和 ErrorHandler 不改，网关就只是个玩具：
-
Director必须重设req.URL.Scheme、req.URL.Host和req.URL.Path：- 否则后端 HTTPS 服务收到
http://...URL 会强制 301 跳转； -
req.Host不显式赋值，云负载均衡器或 Nginx 可能因 Host 头缺失直接拒绝请求； -
req.URL.Path不清理前缀（如/api/v1），会导致路径错位，后端返回 404。
- 否则后端 HTTPS 服务收到
-
Transport必须自定义连接池：-
http.DefaultTransport默认MaxIdleConnsPerHost = 0，高并发下文件描述符迅速耗尽； - 建议配置
DialContext.Timeout（5s）、IdleConnTimeout（30s）、MaxIdleConnsPerHost（100）； - 否则连接复用失效，每个请求新建 TCP 连接，延迟飙升。
-
-
ErrorHandler必须输出 JSON 错误：立即学习“go语言免费学习笔记（深入）”；
- 默认只调用
WriteString，返回纯文本，前端无法解析； - 需手动设置
Content-Type: application/json、状态码（如http.StatusBadGateway），再用json.NewEncoder输出结构化错误体。
- 默认只调用
真实客户端 IP 怎么透传才可靠
req.RemoteAddr 在有 LB 或 CDN 时返回的是中间节点地址，不是真实用户 IP：
- 优先读
X-Real-IPheader； - 若为空，从
X-Forwarded-For按逗号分割，从右往左遍历，跳过私有网段（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16），取第一个合法公网 IP； - 在
Director中写入：req.Header.Set("X-Real-IP", realIP(req))； - 同时设置
X-Forwarded-Proto（根据req.TLS != nil判断）和X-Forwarded-For（追加当前真实 IP，非覆盖）； - 务必删除 hop-by-hop header：
req.Header.Del("Connection")、req.Header.Del("Keep-Alive")、req.Header.Del("Proxy-Authenticate")，否则后端可能解析异常或报错。
路径重写为什么不能用正则替换
用strings.Replace 或第三方 path rewrite 库做前缀替换，极易破坏语义边界：
- 例如把
/api/v1/users替换为/users，若请求是/api/v1/user-profile，会被错切成/user-profile，丢失v1版本信息； - 正确做法是严格前缀匹配：
strings.HasPrefix(req.URL.Path, "/api/v1")，再用strings.TrimPrefix(req.URL.Path, "/api/v1")截取； - 绝对不要碰
req.URL.EscapedPath()—— 它含原始编码，直接赋值会导致路径二次解码错误； - 所有路径操作应在
Director中完成，且仅作用于req.URL.Path，不碰 Query 或 Fragment。
复杂点不在“能不能转发”，而在“转发时是否保留语义、连接是否可控、错误是否可观察”。这些细节不抠清楚，网关上线后的问题都是深夜告警。
