Go服务端流量染色需全链路显式传递X-Gray-ID：HTTP每层中间件须提取header并新建context，gRPC需逐跳手动读写metadata，fasthttp需UserValue+类型断言，严禁隐式依赖context.Value或自动透传。
Go 服务端流量染色不是加个 X-Gray-ID 就完事，而是确保这个标识从入口请求开始，到所有下游 HTTP/gRPC 调用、日志、DB 连接池、缓存 client 全部感知并延续——漏一环，灰度就失效。
HTTP 中间件必须每层显式提取 header 并注入 context
常见错误是网关层用 context.WithValue(ctx, grayKey, val) 写一次，后续 handler 直接 ctx.Value(grayKey) 取值。这不可靠：任意中间件（日志 wrapper、panic 恢复、auth 校验）都可能新建 context，覆盖上游值。
- 所有 HTTP handler 前必须加统一中间件，调用
r.Header.Get("X-Gray-ID")提取值 - 立即用
context.WithValue(ctx, grayKey, val)构建新 context，不信任上游传来的 ctx - 若用
gin.Context，推荐c.Set("gray-id", val)+c.MustGet("gray-id").(string)，比原生 context 更可控、类型安全 - 避免用字符串字面量当 key，定义
type grayCtxKey string; var GrayIDKey grayCtxKey = "gray-id"防 key 冲突
下游 HTTP 请求必须手动设置 header，net/http 不会自动透传
现象：A 服务收到带 X-Gray-ID: v2 的请求，调 B 时 B 收不到该 header。这不是 bug，是 net/http 明确设计——incoming headers 和 outgoing headers 完全隔离。
- 每次构造
http.Request后，必须显式调用req.Header.Set("X-Gray-ID", grayID) - 注意大小写：用
http.CanonicalHeaderKey("x-gray-id")确保设的是X-Gray-ID，而非x-gray-id或X_gray_ID - 别改
gin.Context.Request.Header，它只影响当前 request 生命周期，不会带到下游 - 封装通用 HTTP client 工具函数时，参数必须显式接收
grayID string，禁止隐式从 context 取（易漏传、取错）
gRPC 场景下 metadata 必须逐跳显式读写，context.WithValue 不生效
gRPC 的 context 传播机制和 HTTP 完全不同。context.WithValue 里的灰度字段不会自动变成 wire 上的 metadata，server 端也收不到；更关键的是，metadata 不会自动向下一级透传——A→B→C，B 不主动提取再注入，C 就收不到。
立即学习“go语言免费学习笔记（深入）”；
- client 发起调用前：构造
md := metadata.Pairs("x-gray-id", grayID)，再用grpc.Header(&md)或metadata.NewOutgoingContext(ctx, md) - server 端拦截器中：用
metadata.FromIncomingContext(ctx)提取，再调md.Get("x-gray-id")（注意小写 key，"x-gray-id"，不是"X-Gray-ID"） - B 服务调 C 时，必须重复上述过程：提取 → 构造 md → 注入 outgoing context，不能依赖“自动转发”
- 禁止在 gRPC 拦截器里做
ctx.Value()判断，那永远为空
fasthttp 和无 context 场景要用 UserValue + 类型断言
fasthttp.RequestCtx 没有标准 context.Context 支持，ctx.Value() 是空接口，直接断言失败会 panic。
- 存值：用
ctx.UserValue("gray-id")，它返回interface{} - 取值：必须做类型断言，如
v, ok := ctx.UserValue("gray-id").(string)，否则 runtime panic - 不要在中间件里查 Redis 或 DB 判断灰度规则；应预热到内存 map 或用 LRU cache，否则每次请求都阻塞
- 灰度路由决策必须在入口中间件完成，不能拖到 handler 里——DB 连接池、缓存 client 已按默认配置初始化，再切就晚了
真正难的不是加一个 header，而是让整个调用链上每个环节都“记得”自己该传什么、该信什么、该拒绝什么。最容易被忽略的点是：gRPC 多跳场景下 metadata 的显式再注入，以及 fasthttp 中类型断言的强制要求——不写 .(string) 看似省事，上线后 panic 就在等你。
