灰度标识必须从http/grpc入口开始全程透传。需在路由前注册中间件统一提取header/query参数并注入context，grpc需每跳显式透传metadata，服务发现应基于元数据打标而非硬编码路由，日志与链路追踪须携带release_phase字段确保可观测性。
HTTP中间件提取灰度标识必须放在路由前
中间件顺序错了，灰度逻辑就失效。Gin/Echo里常见错误是把灰度判断写在鉴权或缓存中间件之后，结果请求被提前拦截，根本没走到灰度分支。
- 分流逻辑必须在
router.Use()最开头注册，确保所有请求都经过它 - 别用
c.Param("version")解析灰度标识——路径参数和灰度无关，应统一从c.Request.Header.Get("X-Release-Phase")或c.Query("stage")读取 - 提取后立刻存入 context：
ctx := context.WithValue(c.Request.Context(), "release_phase", phase)，后续 handler 用c.Request.Context().Value("release_phase")取 - 禁止在中间件里改
c.Request.URL.Path后直接c.Next()——这会让 Gin 的路由匹配失败，要用c.Redirect()或显式调用目标 handler 函数
gRPC Metadata 必须每跳显式透传
gRPC 的 metadata.MD 不会自动跨服务传播，A→B→C 链路中只要 B 没手动提取再附加，C 就收不到灰度标识。
- 客户端发起调用前：用
metadata.NewOutgoingContext(ctx, metadata.Pairs("x-release-phase", "v2-beta")) - 服务端接收时：调用
metadata.FromIncomingContext(ctx)，再用md.Get("x-release-phase")判断 - 若需继续往下传（B 调 C），必须用
metadata.AppendToOutgoingContext(ctx, "x-release-phase", phase)显式追加，不能依赖中间件自动挂载 - 对接
grpc-gateway时，启动时要加runtime.WithMetadata(func(ctx context.Context, r *http.Request) metadata.MD { return metadata.Pairs("x-release-phase", r.Header.Get("X-Release-Phase")) })
服务发现层打标比硬编码路由更可靠
在业务代码里写 if phase == "v2" { callUserServiceV2() } 是反模式——无法动态调整、污染核心逻辑、回滚困难。
- 所有实例统一注册为
user-service，但带上元数据：map[string]string{"version": "v2.1.0", "stage": "canary", "weight": "15"} - 客户端负载均衡时，先拉全量实例列表，再根据上下文中的灰度标识做本地过滤，比如只选
s.Metadata["stage"] == "canary"的节点 - 用
go-micro时，实现selector.Selector接口，在Select()方法里解析opts.Context中的灰度信息并筛选 - 避免把版本写进服务名（如
user-service-v2）——这会让服务发现语义混乱，且无法做权重灰度
灰度日志和链路必须带上下文字段
日志里没 release_phase 字段，等于灰度流量“隐身”了。排查问题时根本分不清哪条是灰度调用。
- 入口中间件中，用
zerolog.Ctx(r.Context()).Str("release_phase", phase).Msg("request start")注入日志上下文 - OpenTelemetry 的 Span 必须设 tag：
span.SetTag("release_phase", phase)，否则 Jaeger/Kibana 无法按灰度过滤调用链 - 第三方 SDK 回调、DB SQL 日志、异步任务日志，若没显式传入
context.Context，灰度字段就会丢失——得手动补全 - 禁止在 handler 里用
log.Printf，它不继承 request context；所有日志必须通过zerolog.Ctx(c.Request.Context())或类似方式获取
if phase == "v2"，而是让灰度标识从网关进来那一刻起，完整、稳定、无损地贯穿整个调用链——包括 HTTP header、gRPC metadata、服务发现标签、日志上下文、指标维度，缺一不可。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
