灰度路由必须由服务自身控制，通过解析请求上下文（如 Cookie、Header）提取标识并哈希取模决定版本，避免网关简单分流导致语义脱节；新老版本需兼容数据库 schema 与缓存 key，日志和 metrics 必须带 version 标签以保障可观测性。
灰度路由逻辑必须由服务自身控制，不能只靠网关
网关（如 Nginx、API Gateway）做简单比例分流，容易和真实业务语义脱节——比如同一个用户在不同请求中被分到不同版本，导致 session 错乱或事务中断。Golang 服务需要自己解析请求上下文，决定该走老逻辑还是新逻辑。
常见错误现象：HTTP 502 或 context canceled 频发，其实是网关超时后重试，而下游两个版本服务响应时间不一致，放大了抖动。
- 优先从
Cookie或Header（如X-User-ID、X-Gray-Flag）提取标识， fallback 到IP哈希（仅限调试，不可用于生产） - 用
sha256.Sum64对用户标识哈希，再对灰度比例取模，比rand.Float64()更稳定可复现 - 避免在中间件里直接写分支逻辑；把灰度判定抽成独立函数，例如
shouldUseNewVersion(ctx context.Context) bool
新老版本共存时，数据库 schema 和缓存 key 必须兼容
灰度不是“切流量”，是“切行为”——同一时刻，老代码和新代码可能同时读写同一张表、同一个 Redis key。如果新版本写了新字段但老版本没处理，就会丢数据或 panic。
使用场景：上线带字段变更的订单服务，灰度期间部分请求走 v2（加了 refund_reason 字段），部分仍走 v1。
立即学习“go语言免费学习笔记（深入）”；
- 所有新增 DB 字段必须设默认值或允许
NULL，且老版本 ORM 映射结构体不 panic（如 GORM 的gorm:"default:null"） - 缓存 key 建议带上版本前缀，例如
cache:GetOrder:<code>v1:123 和cache:GetOrder:<code>v2:123 分开存，避免互相污染 - 不要在灰度逻辑里删老缓存——新版本写入后，老版本下次读可能直接 miss，而不是读到脏数据
http.ServeMux 不支持路径级灰度，得换 httprouter 或 chi
http.ServeMux 是静态路由，没法在匹配后动态改 handler。你想对 /api/order 这个路径按用户分流，它做不到。
性能影响：用 chi 的 With 中间件做灰度判断，比每次进 handler 再 if-else 略高开销，但实测 QPS 下降不到 3%，可接受。
- 推荐用
chi：在路由定义处用router.With(grayware).Get("/api/order", orderHandler)，grayware是一个中间件，内部调shouldUseNewVersion - 别在
http.HandlerFunc里硬塞 if 分支——会污染业务逻辑，也难测 - 如果已用
gorilla/mux，注意它的Subrouter不自动继承中间件，得显式sub.Use()
日志和 metrics 必须带灰度标签，否则查问题等于盲人摸象
线上报错时，你看到一条 failed to parse json，但不知道这请求走的是 v1 还是 v2。没有灰度维度的日志，等于没日志。
容易踩的坑：用 log.Printf 打日志，却没把灰度结果传进去；Prometheus metrics 没加 {version="v1"} 标签，导致无法对比延迟差异。
- 在 request context 里塞入
ctx = context.WithValue(ctx, grayKey, "v2")，所有日志中间件统一取这个值打 tag - 用
promauto.NewHistogramVec定义指标时，Labels一定要包含version，例如http_request_duration_seconds{version="v2",path="/api/order"} - 不要依赖日志文本里写 “using v2 logic” —— grep 不可靠，结构化日志字段才可聚合
json:",omitempty"，会让灰度变成线上事故预演。 
