哈希分流必须用 x-request-id 而不是 time.now()，因前者由网关统一注入、全链路唯一稳定，确保同一请求始终路由一致；后者每次调用值不同，导致灰度失效且高并发易碰撞。
为什么哈希分流必须用 X-Request-ID 而不是 time.Now()
哈希分流的核心目标是“同一请求始终走同一路”，避免事务中断或状态不一致。用 time.Now().UnixNano() 生成随机数看似简单，但高并发下容易碰撞，且每次请求哈希值都不同，用户刷新一次就跳版本——灰度就失效了。
真实场景中，X-Request-ID 是最稳妥的哈希源：它由网关统一注入、全链路透传、唯一且稳定。即使你没显式设置，很多反向代理（如 Nginx、Envoy）也会自动生成并透传该头。
- 别用
r.RemoteAddr或r.Header.Get("X-Forwarded-For")：IP 可能被代理覆盖或复用，不唯一 - 别用
rand.Intn()：无 seed 控制时行为不可复现，线上排查无从下手 - 哈希算法选
fnv.New32a()足够快且分布均匀，比sha256轻量得多
哈希取模怎么写才不越界、不偏移
权重配置必须是整数（0–100），否则分流比例会失控。比如你想 70/30 分流，weight 参数传 70，而不是 0.7 或 70.0——Go 的 % 运算符只支持整数，浮点数会编译报错或 panic。
关键代码逻辑必须带边界检查：
hash := fnv.New32a()
io.WriteString(hash, r.Header.Get("X-Request-ID"))
mod := int(hash.Sum32() % 100)
if mod 99 {
mod = 0 // 防止极端情况，但实际不会触发
}
if mod
-
weight值必须在 0–100 之间，超出范围应panic或打log.Warn，不能静默 fallback - 别直接用
hash.Sum32() % uint32(weight)：类型不匹配，%左右操作数类型必须一致 - 哈希结果转
int后再取模，避免符号位干扰（Sum32()返回uint32，但% 100在int下更直观）
灰度中间件必须放在最外层，顺序错了就白写了
分流决策必须发生在日志、鉴权、限流、recover 等中间件之前。如果灰度逻辑写在某个 handler 里，DB 连接池、缓存 client、甚至 trace 初始化可能已经按默认配置执行完毕，再切版本也晚了。
以 chi.Router 为例，正确写法是：
r := chi.NewRouter()
r.Use(grayMiddleware) // 必须放第一行
r.Use(loggingMiddleware)
r.Use(authMiddleware)
r.Post("/api/order", orderHandler)
- 用
gorilla/mux时，必须用Subrouter().Use()，别用MatcherFunc：后者执行时机不确定，还可能跳过健康检查路径 - 禁止在 handler 内部写
if r.Header.Get("X-Gray-Version") == "v2"：这已错过路由决策点，无法影响下游调用目标 - 中间件职责要单一：只提取 + 存入
context.WithValue，不做重定向、不手动调另一个 handler
HTTP 客户端透传灰度头时最容易漏掉的三件事
上游服务收到 X-Gray-Version: v2，调下游却收不到——这不是 bug，是 Go 标准库的明确设计：http.Request.Header 和下游请求完全隔离。
- 必须显式调
req.Header.Set("X-Gray-Version", grayID)，不能依赖自动继承 - 注意大小写：用
http.CanonicalHeaderKey("x-gray-version")确保设成X-Gray-Version，否则某些代理可能丢弃 - 别改
gin.Context.Request.Header：它只影响当前 request 生命周期，不会带到下游 HTTP 请求里
封装通用 HTTP client 时，参数里必须显式传入 grayID string，而不是从 context 里隐式取——容易漏传或取错 scope。
