灰度中间件必须置于gin路由链最前端，否则分流失效；需用c.request.withcontext()注入上下文，禁止在handler中硬编码分流逻辑，须用确定性哈希（如fnv.sum64string）实现用户级一致性分流。
灰度中间件必须放在 Gin 路由链最前面
顺序错了，灰度就失效。日志、鉴权、限流等中间件如果注册在灰度逻辑之前，会导致流量已按旧规则处理完才切版本——比如鉴权中间件用 v1 规则放行了请求，后续再进 v2 handler 就可能因权限字段缺失而 panic。
正确做法是：router.Use(GrayMiddleware) 必须是第一个 Use() 调用；若用 http.Handler 包裹，也得确保它是整个链最外层。
- 错误示例：
r.Use(loggingMiddleware); r.Use(authMiddleware); r.Use(GrayMiddleware)—— 日志里永远看不到X-Release-Phase - Gin 中提取标识后，必须用
c.Request = c.Request.WithContext(ctx)注入，后续 handler 才能通过c.Request.Context().Value("stage")取到 - 别在中间件里调
c.Redirect()或手动调两次c.Next()，会破坏 body 读取和 header 传递
分流逻辑不能写死在 Handler 里
把 if c.GetHeader("X-Release-Phase") == "v2" 塞进某个 GET("/user", ...) 的 handler，等于放弃整条链路的灰度一致性。下游服务、指标打标、链路追踪全都会错乱。
分流只做一件事：提取标识 → 计算目标版本 → 注入 context → 交给统一 handler 分发。
- 推荐用 map 映射：
handlers := map[string]gin.HandlerFunc{"v1": v1UserHandler, "v2": v2UserHandler} - 中间件查表选一个执行：
handlers[phase](c)，而不是在每个接口里重复判断 - 禁止用
rand.Float64()随机分流——同一用户刷新页面可能命中不同版本，DB 写入、缓存 key、前端状态全抖动 - 必须用确定性哈希，例如：
fnv.Sum64String(userID) % 100 表示 5% 用户固定走灰度
HTTP Header 透传失败的常见原因
上游加了 X-Release-Phase: v2，下游 c.GetHeader("X-Release-Phase") 却为空，不是 Gin 问题，而是标准库默认不透传非标准 header。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
net/http.Transport 不自动转发自定义头，Gin 中间件也不会帮你拷贝到下游请求里。
- 手动透传：发起 HTTP 请求前，遍历
upstreamReq.Header，对每个X-*头调用req.Header.Add(k, v) - 注意
http.CanonicalHeaderKey会把x-release-phase转成X-Release-Phase，匹配时要用规范名 - 别在
c.Request.Header上直接Set后就以为下游能收到——它只影响当前请求生命周期 - 若用
grpc-gateway，必须配runtime.WithMetadata(func(ctx context.Context, req *http.Request) metadata.MD {...})才能把 header 映射为 gRPC Metadata
灰度标识不该由业务 handler 解析
真正难的不是怎么写 if 判断，而是让这个标识从网关入口开始，全程可追溯、可收敛、可熔断。一旦让每个 handler 自己解析 header，就等于把灰度策略散落在几十个文件里，配置一变，漏改一个就出问题。
所有灰度路径必须打统一日志字段，例如 log.WithField("release_phase", phase)；DAO 层严禁读取灰度配置——SQL 拼接、索引选择、主从延迟行为一旦分叉，排查成本指数级上升。
接口抽象比硬编码更关键：用 UserService interface，启动时根据 phase 注册 v1UserSvc 或 v2UserSvc 实现，handler 里只依赖 interface。这样灰度开关关掉，代码完全不动，只是注入的对象变了。
