灰度路由适配器必须用中间件封装，不可嵌入handler：需提取标识、匹配策略、注入context，通过子路由限定作用域，避免全局拦截；标识提取按header→cookie→query→ip顺序，配置热更新用fsnotify+atomic.value，禁止远程调用和动态正则编译。
灰度路由适配器必须用中间件封装，别塞进 handler 里
灰度路由不是“某个接口要不要走新逻辑”，而是“请求进来时，立刻决定它该进哪条处理链”。硬编码在 http.HandlerFunc 里写 if req.Header.Get("X-Release-Stage") == "canary" 会导致：同一份代码既要处理主逻辑又要判灰度、无法复用、测试难覆盖、上线后改规则就得发版。
正确做法是把灰度决策抽成独立中间件，只做三件事：提取标识、匹配策略、注入 context。后续所有 handler 都从 ctx.Value() 拿结果，不碰 header、不重复计算。
- key 类型别用字符串，定义为
type grayKey string，防止键名冲突 - 中间件必须在日志、panic recover 等中间件之前注册，否则 panic 后 context 丢失，灰度标记失效
- 别在中间件里调
w.WriteHeader()或写响应体——它只负责分流，不负责返回内容
gorilla/mux 或 chi 的 Subrouter/Group 是隔离灰度路径的唯一可靠方式
直接给全局 router 加 Use(grayMiddleware) 是最常见翻车点：健康检查 /healthz、metrics 接口、静态资源全被拦住，服务注册中心误判实例不健康。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
必须用子路由限定作用域。比如灰度只对 /api/v1/order 生效，那就只挂到对应子路由上，主路由完全不受影响。
- gorilla/mux：用
r.PathPrefix("/api").Subrouter()创建子路由，再对子路由调Use() - chi：用
r.Group(func(r chi.Router) { ... })或r.With(grayMiddleware).Route("/order", ...) - 路径前缀别用
/v2这类语义化版本号——它是 API 版本，不是灰度标识；混用会让后续升级和灰度开关互相干扰
灰度标识提取顺序和 Header 处理有坑，优先级必须明确
r.Header.Get("X-Gray-Key") 看似简单，但实际容易漏掉大小写标准化、空值判断、多值覆盖等问题。HTTP Header 名称不区分大小写，但 r.Header["X-Gray-Key"] 返回的是 []string，如果没值会是空切片，不是 nil，直接取 [0] 会 panic。
- 永远用
r.Header.Get("X-Gray-Key")，它内部已做http.CanonicalHeaderKey标准化，传"x-gray-key"或"X-GRAY-KEY"都能命中 - 提取顺序建议固定为：Header → Cookie → URL Query → IP（IP 仅作兜底，慎用）
- 敏感 header 如
Authorization、Cookie必须白名单透传，别无脑req.Header.Clone()，否则可能泄露凭证
配置热更新不能靠轮询，atomic.Value + fsnotify 是最小可行方案
灰度比例、白名单用户 ID、开关状态这些，写死在变量里或只在启动时读一次配置文件，等于放弃灰度的核心价值——随时切流。但每秒 os.ReadFile 轮询又浪费 CPU，还容易漏变更。
- 用
fsnotify.Watcher监听配置文件（如gray.yaml），事件触发后解析新内容 - 把规则封装成只读结构体，用
atomic.Value.Store()原子替换，避免锁竞争 - 禁止在匹配函数里调远程服务或查 DB——超时或失败会拖垮整个请求链路
- 正则表达式提前编译好存为包级变量，比如
var canaryUserRe = regexp.MustCompile(`^u[0-9]{6}$`)，别每次请求都regexp.Compile
canary_version 字段，出问题时根本分不清请求走的是哪条路径；数据库连接池没隔离，灰度版本可能误写生产表。这些细节比中间件逻辑更关键，也更容易被忽略。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
