Golang微服务中API网关的设计与实现_技术教程

net/http 不适合作为 API 网关，因其缺乏动态路由、熔断限流、鉴权等能力，且无法热加载配置、统一错误处理和安全转发；需用可插拔中间件链+服务发现+自研鉴权等构建真正网关。

为什么不能直接用 `net/http` 搭 API 网关

微服务场景下，net/http 的 http.ServeMux 缺乏路由元数据支持、无法动态加载规则、不提供熔断/限流/鉴权等中间件抽象。它适合单体 HTTP 服务，但作为网关会迅速变成维护黑洞——每次加一个限流策略就得改主逻辑，每个新服务上线都要重启进程。

真实项目中更倾向用成熟网关框架（如 Kong、Tyk）或自研轻量网关。Golang 生态里，gorilla/mux + go-chi/chi 是常见组合，但它们仍是路由库，不是网关。真正需要的是在路由之上叠加可插拔的处理链。

必须能从配置中心（如 etcd 或 consul）热加载服务发现列表
转发前需统一校验 Authorization header 并解析 JWT，失败直接 401，不进后端
对 /payment/** 路由需强制启用 rate.Limiter，且配额按 client_id 维度隔离
所有出错响应要统一封装成 {"code":500,"message":"upstream timeout"} 格式，不能暴露下游错误细节

`httputil.NewSingleHostReverseProxy` 的坑与绕过方式

Go 标准库的 httputil.NewSingleHostReverseProxy 看似开箱即用，但它默认不重写 Host 头、不透传原始客户端 IP、超时不可细粒度控制，且不支持重试。直接用于生产网关大概率引发 502 或上游日志混乱。

关键修改点必须手动覆盖：

设置 Director 函数重写 req.URL.Host 和 req.Host，否则后端看到的是网关本机地址
用 req.Header.Set("X-Real-IP", realIP) 透传客户端真实 IP（从 X-Forwarded-For 解析）
替换 Transport：禁用 HTTP/2（某些老服务不兼容），设置 MaxIdleConnsPerHost 防连接耗尽，显式指定 ResponseHeaderTimeout
错误处理不能只靠 proxy.ErrorHandler，需在 Director 前检查目标服务是否健康（查本地缓存或调用健康检查端点）

director := func(req *http.Request) {
    // 从服务发现获取实际 targetURL
    target, ok := serviceRegistry.Get(req.Context(), req.URL.Path)
    if !ok {
        http.Error(req.Response, "service not found", http.StatusNotFound)
        return
    }
    req.URL.Scheme = target.Scheme
    req.URL.Host = target.Host
    req.Host = target.Host
    req.Header.Set("X-Real-IP", getClientIP(req))
}

如何让路由配置支持服务发现和路径重写

硬编码 chi.Router().Route("/user", ...) 违背网关核心价值——解耦。真实配置应类似：

routes:
- path: "/api/v1/users/{id}"
  upstream: "user-service"
  rewrite: "/v1/users/{id}"
  methods: ["GET", "PUT"]
  auth: true
  rate_limit: "100-RPS-per-client"

实现要点：

解析配置时，把 {id} 这类占位符转为正则捕获组，生成 chi.Route 时用 chi.URLParam(r, "id") 提取
upstream 字段触发服务发现：查 consul health service user-service，取 passing 状态实例，轮询更新本地 endpoint 列表
rewrite 不是简单字符串替换，需用 url.PathEscape 处理路径参数值，避免注入 ../
所有路由注册必须在单独 goroutine 中监听配置变更事件，调用 chi.Mux().ServeHTTP 前原子替换 chi.Router 实例

JWT 鉴权中间件必须自己写，别信第三方包

很多 go-jwt-middleware 类库假设 JWT 在 Authorization: Bearer xxx，但实际微服务可能要求从 cookie、X-API-Key 或混合位置提取；还有的强制校验 exp 却忽略 nbf，导致时间不同步时大面积 401。

精简可靠的写法：

用 golang.org/x/oauth2/jws 解析 token，不用 github.com/dgrijalva/jwt-go（已归档且有安全争议）
密钥获取走回调函数：func(ctx context.Context) ([]byte, error)，支持从远程 KMS 动态拉取
claims 校验后必须调用 token.Claims.VerifyAudience("gateway", true)，防止被滥用于其他系统
鉴权失败返回 http.StatusUnauthorized 且清空响应 body，避免泄露 token 结构信息

func JWTAuthMiddleware(jwtKeyFunc func(context.Context) ([]byte, error)) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            tokenStr := parseTokenFromRequest(r)
            key, err := jwtKeyFunc(r.Context())
            if err != nil {
                http.Error(w, "auth failed", http.StatusUnauthorized)
                return
            }
            token, err := jws.Parse(tokenStr, jws.WithKey(jwa.HS256, key))
            if err != nil || !token.Valid() {
                http.Error(w, "invalid token", http.StatusUnauthorized)
                return
            }
            // 注入到 context 供后续 handler 使用
            ctx := context.WithValue(r.Context(), "claims", token.Claims())
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

网关最难的部分从来不是转发，而是当 10 个团队同时提需求：A 要 OpenTelemetry 上报，B 要 WAF 规则，C 要灰度 header 透传——这时候路由树和中间件链的组织方式，决定了你下周是改代码还是写辞职信。