灰度发布是架构层流量控制问题，golang服务只负责透传标识，路由由网关/sidecar实现；http需手动透传header并防代理过滤，grpc需逐跳显式传递metadata，服务注册须带标签而非ip，envoy+xds是最稳落地方式。
灰度发布不是 Golang 语言能力，而是架构层的流量控制问题。Golang 微服务本身不提供灰度能力，所有“切换”都发生在网关、服务发现或 Sidecar 层——服务代码只负责识别和透传标识，不决定路由。
HTTP 请求头必须显式透传，否则下游收不到
常见错误是上游加了 X-Gray-Version，但下游 r.Header.Get("X-Gray-Version") 返回空。Go 的 http.Transport 默认不转发自定义 Header，gin/echo 中间件也不会自动携带。
- 在客户端发起请求前，手动拷贝关键 Header：
for k, vs := range upstreamReq.Header { for _, v := range vs { req.Header.Add(k, v) } } - 避免用
req.Header.Set("X-Gray-Version", "v2")后直接client.Do(req)——必须确保该 Header 不被中间代理（如 Kong、APISIX）静默 strip，需配置enable-access-log或显式放行X-*类 header - 若用
net/http.RoundTripper封装透传逻辑，注意http.CanonicalHeaderKey会把x-gray-version转成X-Gray-Version，匹配时要统一大小写
gRPC Metadata 必须逐跳显式读写，不能靠中间件自动传播
gRPC 的 metadata.MD 是单向且只读的：client 发送的 metadata 只能被 server 读取，server 想传给下一级，必须自己提取再附加。
- client 侧发送：
md := metadata.Pairs("x-gray-version", "v2"); ctx = metadata.NewOutgoingContext(ctx, md) - server 侧接收：
md, ok := metadata.FromIncomingContext(ctx); if ok { version := md.Get("x-gray-version") } - 若链路是 A→B→C，B 在处理完自己的逻辑后，必须用
metadata.AppendToOutgoingContext(ctx, md)把原始灰度标识再带上，否则 C 收不到 - 用
grpc-gateway时，需启用runtime.WithMetadata才能把 HTTP Header 映射为 gRPC Metadata
服务注册必须带标签，不能靠 IP 或端口区分灰度
灰度实例的识别依据是注册中心里的元数据（metadata），不是地址。K8s Pod IP 或端口滚动更新后会变，硬编码路由必然失效。
- Consul 注册示例：
service.Tags = []string{"version:v2", "gray:true"}，查询时用services?tag=gray:true - Nacos 注册示例：
Metadata: map[string]string{"version": "v2", "env": "gray"}，网关调用nacos.SelectInstances时按metadata["version"] == "v2"过滤 - 不要用 DNS 做服务发现——CoreDNS 不支持按 metadata 筛选，必须换用支持标签过滤的 client SDK（如
go-micro/registry/nacos的 Selector 插件） - 若用原生
grpc-go，需自定义balancer.RoundRobin子类，在Pick方法中解析 ctx 里的 metadata 并筛选目标实例
Envoy + xDS 是生产环境最稳的灰度落地方式
纯 Go 实现路由规则容易陷入状态同步延迟、权重抖动、热更新不及时等问题。高并发场景下，应把灰度逻辑下沉到 Sidecar。
- 用 Envoy 的
route.match.headers匹配X-User-Id范围，或用runtime_key动态开关灰度比例 - Golang 服务只需专注业务，不再维护
if gray { call v2 } else { call v1 }这类分支逻辑 - 验证是否生效：直接
curl -H "X-User-Id: 12345" http://svc/，看 Envoy accesslog 是否命中cluster_name: order-v2-gray - 注意 Envoy 默认拒绝含下划线的 Header（如
X_Gray_Version），需在http_protocol_options中设headers_with_underscores_action: ALLOW，否则会被静默丢弃
真正难的不是写几行分流代码，而是让灰度标识从入口到数据库全程不丢失、不歧义、不漂移——每个中间节点都要确认它是否透传、是否被过滤、是否被大小写转换，漏掉一环，整个灰度链路就断了。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
