灰度发布通过@GrayEnable注解实现按需、就近、非侵入的环境平滑切换，依托AOP拦截+运行时上下文提取+配置中心动态规则匹配，支持端到端透传、异步手动携带、自动熔断降级与可观测监控。
灰度发布中，通过局部范围内的注解属性覆盖来实现环境平滑切换，核心在于“按需生效、就近控制、不侵入主逻辑”。关键不是全局开关，而是让某个服务调用、某个方法执行、甚至某次 HTTP 请求，能基于运行时上下文（如请求头、用户 ID、标签）动态启用/禁用新逻辑，且配置粒度可控、无需重启。
用自定义注解标记可灰度的代码单元
定义如 @GrayEnable 注解，支持属性如 feature = "payment-v2"、strategy = "header:gray-tag"、fallback = "v1"。它不直接做判断，只声明“此处可灰度”，把决策权交给统一的灰度处理器。
- 注解保留在
RUNTIME生命周期，配合 AOP 或 Spring 的@Around切面拦截 - 支持类级和方法级，方法级优先级高于类级，便于细粒度控制
- 避免在注解里写死条件表达式（如
condition = "#user.tag == 'beta'"），应交由外部规则引擎或配置中心解析
运行时从上下文提取灰度标识并匹配规则
每次进入被 @GrayEnable 标记的方法前，切面从当前线程上下文（如 RequestContextHolder）提取标识：可能是 HTTP Header 中的 X-Gray-Tag、JWT 中的 group 字段、或 ThreadLocal 存储的测试用户 ID。
- 将提取的标识与配置中心（如 Nacos/Apollo）中维护的灰度规则比对，例如：
payment-v2 → tag in [beta, canary] - 匹配成功则激活新逻辑（如调用
PaymentServiceV2），否则走默认分支（PaymentServiceV1） - 规则支持动态刷新，变更后 5 秒内生效，无需发版
属性覆盖要分层隔离，避免跨作用域污染
“局部范围”意味着灰度状态不能泄露到无关链路。比如一个灰度请求触发了下游服务调用，下游也需识别并延续该灰度上下文，但必须显式透传，不可隐式继承。
- 使用
GrayContext.bind(tag)主动绑定，并在方法退出时自动清理（AOPafterReturning或afterThrowing） - RPC 调用（如 Dubbo/Feign）需自动注入灰度标头，下游服务通过相同机制识别，形成端到端灰度链路
- 异步任务（如 Kafka 消费、定时任务）默认不继承灰度态，如需支持，须手动携带
GrayContext.snapshot()并在线程池中还原
降级与可观测性是平滑切换的前提
灰度不是开关，而是“有监控的试验”。一旦新逻辑异常率突增或响应延迟超标，应自动熔断并回退，同时确保业务无感。
- 为每个灰度特征配置独立指标（QPS、成功率、P99 延迟），接入 Prometheus + Grafana 实时看板
- 当错误率 > 5% 持续 60 秒，自动关闭该特征的灰度开关（写回配置中心），并记录 traceId 方便回溯
- 日志中统一打标
[gray:payment-v2,beta]，ELK 中可快速筛选对比新旧逻辑行为差异
