Header灰度路由必须在HTTP中间件中实现，核心是请求进入时立即分流，避免绕过限流、鉴权等前置逻辑；需统一提取X-Gray-前缀Header并校验白名单，透传时用c.Copy()或fasthttp.UserValue()确保安全，且注意大小写容错。
Header灰度路由必须在HTTP中间件里做，不能依赖后端业务逻辑
Go服务做Header灰度，核心是「请求进来时立刻分流」，一旦进到业务Handler再判断，就可能绕过限流、鉴权或缓存等前置逻辑。所以必须在最外层中间件统一提取X-Release-Stage或X-Gray-Version这类Header，解析后写入context.Context并决定下一跳——比如改写r.URL.Path、替换r.Host，或直接http.Redirect到灰度集群入口。
常见错误是把灰度判断放在某个API的Handler里：if r.Header.Get("X-Gray-Version") == "v2" { ... }。这会导致同一请求在日志、监控、链路追踪中被当成两个不同路径处理，且无法对灰度流量统一限流或采样。
- 所有灰度Header名建议统一用
X-Gray-前缀，避免和标准Header（如X-Forwarded-For）冲突 - 值必须做白名单校验，比如只允许
v1、v2、canary，防止恶意Header触发未发布版本 - 中间件要早于日志中间件注册，否则灰度标识不会出现在access log里
gin框架下用gin.Context.Copy()保留原始Header做透传
如果灰度路由需要把请求代理到下游服务（比如调用另一个Go微服务），必须把原始灰度Header透传过去，否则下游无法继续执行灰度逻辑。但c.Request.Header是共享的，直接修改会影响当前请求生命周期内的其他中间件。
正确做法是用c.Copy()创建新上下文副本，在副本里添加/覆盖Header，再用httputil.NewSingleHostReverseProxy转发：
proxy := httputil.NewSingleHostReverseProxy(upstreamURL)
proxy.Director = func(r *http.Request) {
r.Header.Set("X-Gray-Version", c.GetString("gray_version")) // 从ctx取值
r.Header.Set("X-Request-ID", c.GetString("req_id"))
}
注意：不要用c.Request.Header.Set()直接改原请求Header，否则会影响后续中间件对原始Header的判断（比如鉴权中间件依赖原始Authorization）。
-
c.Copy()只复制Context数据，不复制*http.Request，所以Header透传仍需在Director里手动设置 - 若下游是gRPC服务，Header需转成
metadata.MD，键名要小写（如x-gray-version），否则gRPC-go会忽略 - 透传时建议过滤掉敏感Header，比如
Cookie、Authorization，除非明确需要带过去
fasthttp框架因无标准net/http Handler接口，灰度中间件要重写ServeHTTP
fasthttp不走http.Handler，它的RequestCtx没有context.Context字段，也不能用http.HandlerFunc包装。所以gin那套中间件模式不能直接搬过来。
必须在fasthttp.Server.Handler里手动解析Header，并通过ctx.UserValue()存灰度信息：
server := &fasthttp.Server{
Handler: func(ctx *fasthttp.RequestCtx) {
version := string(ctx.Request.Header.Peek("X-Gray-Version"))
if version == "v2" {
ctx.SetUserValue("gray_version", version)
// 跳转或改写path
ctx.Request.SetRequestURI("/api/v2/users")
}
},
}
问题在于ctx.UserValue()是任意类型，没类型安全；而且多个中间件叠加时容易覆盖。更稳妥的做法是定义结构体封装灰度状态：
type GrayState struct {
Version string
Enabled bool
}
ctx.SetUserValue("gray", GrayState{Version: "v2", Enabled: true})
- fasthttp的
Peek()返回[]byte，记得用string()转，别直接拿去比较 - 不能用
ctx.Redirect()做灰度跳转——它会发302响应，暴露灰度路径；应该用ctx.Request.SetRequestURI()内部重写 - fasthttp默认不解析
Content-Type: application/json的body，如果灰度规则依赖JSON body字段，得手动ctx.PostBody()解析
灰度Header匹配要区分大小写，但RFC规定HTTP Header名不区分大小写
表面上看，r.Header.Get("X-Gray-Version")和r.Header.Get("x-gray-version")应该等价，但实际在Go的net/http里，Header底层用map[string][]string存储，key是原始输入的字符串。如果客户端发的是x-gray-version，而你代码里写X-Gray-Version，Get()就返回空。
根本原因是Go的Header类型实现了Get()方法，内部做了规范化（转为canonicalMIMEHeaderKey），但这个规范只对标准Header生效。自定义Header如X-Gray-Version，Go不会自动转成X-Gray-Version，而是原样存。
- 统一用
textproto.CanonicalMIMEHeaderKey("x-gray-version")生成规范key再查，确保大小写容错 - 或者更简单：遍历
r.Header的key，用strings.EqualFold()比对 - 上线前用curl测试各种大小写组合：
curl -H "x-gray-version: v2" /api/users、curl -H "X-GRAY-VERSION: v2" /api/users
这事容易被忽略，直到灰度流量完全没进来才排查——因为测试环境客户端都按规范写了大写，生产环境某些SDK或网关却用了小写。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
