灰度切流需拆分为标识提取与路由分发两步，中间件仅负责提取并注入灰度ID到context，路由决策须由网关或服务发现层统一管控，禁止硬编码。
灰度切流在 Gin 中不能靠单个中间件“一把梭”完成，必须拆成「标识提取」+「路由分发」两步，且后者不能写死在中间件里。
中间件只负责提取和注入灰度标识，不决定路由走向
常见错误是把 GrayIDMiddleware 写成这样：
func GrayIDMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
grayID := r.Header.Get("X-Gray-Id")
if grayID != "" && shouldRouteToV2(grayID) { // ❌ 错误：在这里做跳转
v2Handler.ServeHTTP(w, r)
return
}
next.ServeHTTP(w, r)
})
}
问题在于：路由逻辑耦合进中间件后，无法动态调整、难测试、违反单一职责。Gin 的中间件本质是请求链路的「钩子」，不是「调度器」。
- 正确做法是只提取并注入：
ctx := context.WithValue(r.Context(), "gray_id", grayID)，然后用c.MustGet("gray_id")或c.GetString("gray_id")在 handler 里读取 - 若使用
gin.Context，注意它底层包装了*http.Request，所以c.Request.Context()和c.Request是同步的 - 避免用
context.Background()替换原 context——会丢失超时、取消等关键信号
灰度路由必须由统一网关或服务发现层接管
业务代码里写 if grayID != "" { callV2() } 是反模式。真实生产中，灰度路由应由以下任一方式驱动：
- API 网关（如 Kong、Nginx+Lua、自研 Go 网关）根据
X-Gray-IdHeader 做 upstream 分组转发 - 服务注册中心（如 Nacos）为实例打标：
metadata: {"version": "v2.0", "canary": "true"}，客户端 SDK 按标签选服务实例 - gRPC 场景下，用
grpc.WithBalancerName(round_robin)+ 自定义balancer.Picker，在Pick()中解析ctx里的灰度信息筛选目标地址
硬编码路由会带来三个后果：配置变更要发版、无法做 AB 测试分流比、下游服务升级时上游也要改代码。
Header 透传必须显式处理，标准库不自动转发
你在入口加了 X-Gray-Id，但调用下游服务时收不到，大概率是没透传。Gin 或 net/http 默认不会把非标准 Header 转发出去。
- 手动拷贝（简单场景）：
for k, vs := range r.Header { for _, v := range vs { req.Header.Add(k, v) }，注意req是你新建的*http.Request - 用
http.RoundTripper封装透传逻辑，重点过滤X-、x-开头的 key，因为http.CanonicalHeaderKey会把它转成X-Gray-Id - Gin 中不要直接改
c.Request.Header，它只影响当前请求生命周期，不影响你后续用http.Client发起的新请求
透传漏掉一个环节，灰度链路就断了——比如 A→B→C，B 提取了灰度 ID 却没传给 C，C 就永远走默认版本。
灰度标识建议用哈希或预计算标签，别传原始敏感字段
有人直接把用户手机号当 X-Gray-Id 传，这是高危操作：
- 手机号明文暴露在日志、监控、链路追踪中，违反 GDPR / 等保要求
- 哈希值更安全：
sha256(fmt.Sprintf("%s:%s", phone, salt))[:16]，既保留一致性又不可逆 - 更推荐用预分配标签，比如运营后台给某批用户打上
group: vip-beta，后端只认这个字符串，不关心背后是谁
灰度不是技术炫技，而是可控的发布节奏。最容易被忽略的点，其实是「灰度标识的生命周期管理」——它该在什么时候生成、在哪里校验、过期怎么清理。这些不在 Gin 框架里，但在你的架构图里必须画清楚。
