Go接口灰度发布必须在最外层中间件用r.Header.Get()提取X-Gray-Version等头，存入自定义context key，并显式透传至下游HTTP请求，分流策略需基于哈希+热更新配置实现用户稳定命中。
Go 接口灰度发布，不能靠 http.ServeMux 做路径路由，必须在中间件层用 r.Header.Get() 提前提取、判断、透传——否则灰度标识进不到业务逻辑，下游服务也收不到。
Header 提取必须用 r.Header.Get()，别碰 r.Header 切片
HTTP Header 名称不区分大小写，但 Go 的 http.Request.Header 是 map[string][]string 类型，直接读 r.Header["X-Gray-Version"] 可能返回空切片或 panic（比如 key 不存在时返回 nil slice，后续 len() 不报错但逻辑出错）。r.Header.Get() 内部做了标准化处理，传 "x-gray-version"、"X-Gray-Version" 都能命中，且返回 string（空字符串表示未找到）。
- 永远检查返回值是否为空：
if version := r.Header.Get("X-Gray-Version"); version != "" { ... } - 禁止用下划线命名 header，如
X_Gray_Version—— HTTP 协议不支持，Nginx 或客户端可能自动丢弃 - 敏感 header 如
Authorization、Cookie不建议用于灰度判断，避免泄露或被篡改；优先用业务语义明确的头，如X-Release-Strategy或X-Env-Tag
分流逻辑必须放在最外层中间件，且只标记不跳转
灰度不是“重定向”，而是让同一请求在整条链路中始终走一致路径。如果把分流逻辑写在某个 handler 里，DB 初始化、缓存连接、日志打点可能已经按默认配置执行过了，再切版本就晚了。
- 中间件顺序很关键：灰度中间件必须在日志、鉴权、recover、限流等中间件之前
- 中间件职责要单一：只做“提取 + 存入 context”，不要调
http.Redirect或手动调用另一个 handler —— 后续路由/反向代理逻辑应基于 context 中的值决策 - 用自定义类型作 context key，避免字符串冲突：
type grayKey string; const GrayKey grayKey = "gray_version" - 注入方式：
ctx := context.WithValue(r.Context(), GrayKey, version); r = r.WithContext(ctx)
Header 值必须透传到下游 HTTP 请求，net/http 不会自动带
这是线上最常踩的坑：A 服务收到 X-Gray-Version: v2，调 B 服务时 B 收不到这个头。因为 http.Client 默认不会复制 incoming headers 到 outgoing request。
立即学习“go语言免费学习笔记（深入）”；
- 每次构造
http.Request前，必须显式设置：req.Header.Set("X-Gray-Version", version) - 注意大小写：用
http.CanonicalHeaderKey("x-gray-version")确保格式统一，避免某些代理（如 Envoy）拒绝非标准头 - 如果封装了通用 client 工具函数，参数里必须显式传入
grayVersion string，而不是从 context 里隐式取 —— 容易漏传、取错、或 context 被覆盖 - 透传要白名单控制：只传
X-*类业务头，不传Authorization、Cookie、Content-Length等系统/敏感头
别硬编码 if/else，策略必须可热更新且用户稳定命中
上线后改个比例就要发版？同一用户在新旧版本间反复跳变？说明策略没抽象好。Header 值只是输入，真正分流逻辑得靠确定性哈希 + 外置规则。
- 用户稳定性靠哈希：用
hash/fnv对 header 值做哈希，再% 100得桶号，比rand.Float64()可靠得多 - 比例控制靠配置：把
{"v2": 15, "v3": 5}这类结构存在内存里，用atomic.LoadPointer原子读取；变更时由 fsnotify 或定时拉取更新指针指向的新快照 - 兜底逻辑要有：header 为空时，按 cookie → query → IP 段顺序 fallback，但 IP 段慎用（NAT 场景下多个用户共用一个出口 IP）
- 上线初期务必验证分布：在日志里打
bucket和version，确认 15% 流量确实落在 v2，且同一用户 ID 始终命中相同 bucket
Header 灰度看着简单，但真正稳住的关键在于：入口提取不漏、context 透传不丢、下游调用不哑、策略更新不卡。任何一环断掉，灰度就变成随机抖动。
