灰度路由规则必须在HTTP中间件中基于请求上下文动态决策，不可硬编码于客户端或handler中；需通过提取X-Gray-Key等标识哈希分流，避免使用如if userID % 10这类静态逻辑。
灰度路由规则必须由请求上下文动态决定，不能硬编码
硬编码 if userID % 10 这类逻辑会让灰度策略无法热更新，且难以测试和回滚。真实场景中，灰度依据可能是 <code>user_id、device_id、header["X-Env"] 或 JWT 中的自定义 claim，必须从 http.Request 或 context.Context 中实时提取。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 把灰度判定逻辑封装为独立函数，例如
func IsInGray(ctx context.Context, req *http.Request) bool，便于单元测试和替换 - 避免在 handler 内直接写
if rand.Float64() —— 这属于随机灰度，不可复现、难排查，应仅用于兜底或压测 - 灰度标识（如
"gray-v2"）建议从配置中心（如 etcd 或 Nacos）拉取，而非常量；变更时通过 watch 机制热刷新sync.Map缓存
HTTP 中间件需透传灰度标识到下游服务
单体服务内灰度容易实现，但微服务链路中，若中间件只改本地 handler 行为，下游服务仍按默认逻辑处理，灰度就断了。关键在于让 X-Gray-Version 或类似 header 贯穿整个调用链。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 在入口中间件中解析灰度规则后，务必调用
req.Header.Set("X-Gray-Version", "v2")，并确保后续所有http.Client请求都复制该 header - 使用
context.WithValue存储灰度版本（如ctx = context.WithValue(ctx, grayKey, "v2")），避免依赖 header 的副作用（比如被代理截断） - gRPC 场景下，改用
metadata.MD{"gray-version": []string{"v2"}}透传，服务端用grpc.Peer或拦截器提取
服务发现客户端要支持按灰度标签过滤实例
如果注册中心返回的实例列表没做过滤，即使上游标了 X-Gray-Version: v2，负载均衡仍可能把请求打到 v1 实例上。这不是代码逻辑问题，而是服务发现层缺失灰度语义。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 不要自己遍历所有实例再 filter —— 这会绕过健康检查、权重等原生能力。应使用支持 metadata 匹配的 client，如
consulapi的QueryOptions.Filter或etcd的WithPrefix+ 标签键约定 - 注册时，每个服务实例上报 tags 类似
["version:v1", "gray:false"]或["version:v2", "gray:true"]，查询时用service=="api" && gray=="true"表达式 - 若用 Kubernetes，可结合
Service的selector和Pod的labels，但注意EndpointSlice不自动支持 label selector 变更，需配合 operator 或自定义 controller
灰度模块必须内置降级开关和采样日志
灰度流量一旦出错，影响面比全量小，但排查难度更高——因为现象是“部分用户失败”。没有开关和日志，等于把问题藏进黑盒。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 提供运行时开关：比如环境变量
GRAY_DISABLE=true或配置项gray.enabled=false，让中间件直接跳过判定逻辑，走默认路径 - 对命中灰度的请求，强制记录结构化日志，至少包含
request_id、gray_version、matched_rule（如"user_id_mod_100_lt_5"）、upstream_instance - 采样率控制很重要：全量打日志会拖慢性能，建议用
log.Sampled(0.01)或基于request_id哈希做固定比例采样
灰度最难的不是怎么切流量，而是怎么确认“切对了”——规则是否生效、下游是否收到、实例是否匹配、错误是否隔离，这些环节任何一个漏掉监控，灰度就变成故障放大器。
