Spring Cloud Gateway通过GlobalFilter+RoutePredicateFactory实现灰度路由，需对齐匹配依据与服务元数据；Nacos注册时须声明version等metadata；Feign调用需RequestInterceptor透传灰度头；规则路由优于权重策略。
Spring Cloud Gateway 怎么做灰度路由？
网关是灰度流量分发的第一道关卡，Spring Cloud Gateway 本身不内置灰度能力，但靠 GlobalFilter + RoutePredicateFactory 可以精准控制每条请求去哪个版本。关键不是写逻辑，而是把「匹配依据」和「目标服务元数据」对齐。
常见错误现象：
- 请求头带了
X-Gray-Version: v2，但网关没转发该 header 给下游，导致服务端收不到灰度标识 - Nacos 注册的服务 metadata 缺少
version=v2，网关查不到对应实例，直接 fallback 到默认路由
使用场景：
- 按用户 ID 哈希取模（
user-id % 100 < 5→ 灰度） - 按请求头
X-Canary-Token存在性判断 - 按 Cookie 中
gray=on开关
实操建议：
- 在
GlobalFilter中解析请求特征后，用ServerWebExchange.getAttributes().put(GATEWAY_REQUEST_URL_ATTR, ...)动态重写目标 URI，或更推荐：通过LoadBalancerClient手动筛选带指定 metadata 的实例 - 必须确保所有下游服务在 Nacos 注册时都声明了
metadata，例如：spring.cloud.nacos.discovery.metadata.version=v2 - 不要依赖 Ribbon（已废弃），Spring Cloud 2020+ 默认用
Spring Cloud LoadBalancer，需确认其支持 metadata 过滤（需自定义ServiceInstanceListSupplier）
Nacos 元数据怎么配才不踩坑？
Nacos 不是“配了 metadata 就自动生效”，它只负责注册和发现，真正的路由决策在客户端（如网关或 Feign）。很多团队卡在这步，以为配置写了就完事。
常见错误现象：
- 在 Nacos 控制台手动给实例加了
gray=true，但网关没读这个字段，流量照旧打全量 - 多个服务共用同一 group，但 version 标签写错成
VERSION=v2（大小写不敏感？错——Nacos metadata 是严格字符串匹配）
参数差异：
-
version是最通用的 key，Spring Cloud Alibaba 默认识别它做版本路由 - 若用自定义 key（如
env=gray），必须同步改网关里的匹配逻辑，不能指望框架自动适配
实操建议：
- 启动参数里统一加：
-Dspring.cloud.nacos.discovery.metadata.version=${APP_VERSION}，避免硬编码 - 不要在控制台手工改 metadata，用 Nacos OpenAPI 或配置中心批量推送，防止遗漏或不一致
- 测试时用
curl -H "X-Gray-Version:v2" <a href="https://www.php.cn/link/bf5a72f10c8a5910f76537e4a7ed07dc">https://www.php.cn/link/bf5a72f10c8a5910f76537e4a7ed07dc</a>配合 Nacos 实例列表页面，实时观察哪些实例被选中
Feign 调用链里灰度标签怎么透传？
服务 A → 服务 B → 服务 C，如果只在网关层打了灰度标，B 调 C 时没带过去，C 就收不到上下文，整个链路就断了。
常见错误现象：
- 网关把
X-Gray-Version传给了服务 A，但 A 用 Feign 调 B 时 header 消失，B 收不到 - 异步线程（如
@Async）里发起 Feign 调用，ThreadLocal 里的请求上下文丢失
性能 / 兼容性影响：
- 每次 Feign 调用都手动 copy header，代码冗余且易漏
- 用
RequestInterceptor是标准解法，但 Spring Cloud 2022.0+ 后需配合feign.client.config.default.request-interceptors配置启用
实操建议：
- 写一个通用
GrayHeaderRequestInterceptor，自动提取当前请求的X-Gray-Version并注入到 Feign 的RequestTemplate - 对
@Async场景，必须用TraceableExecutorService（如 SkyWalking 提供的）或手动 wrap ThreadLocal，否则灰度标必丢 - 不要用
HttpHeaders构造新对象再 set，优先用template.header("X-Gray-Version", value)，避免覆盖已有 header
权重切分 vs 规则路由，什么时候该选哪个？
Istio 的 VirtualService 权重路由看着很美，但生产环境多数团队其实用不上——它依赖 Sidecar，且无法响应业务维度的动态条件（比如“VIP 用户全部走 v2”）。
常见错误现象：
- 盲目套用 Istio 示例，结果发现网关没装 Envoy，或者公司没上 Service Mesh
- 用权重策略做用户级灰度，结果发现 5% 流量里 VIP 用户一个没分到，纯随机导致验证失效
使用场景对比：
-
权重策略：适合压测、冷启动验证，只要求“大概比例”，不要求精准命中 -
规则路由：适合功能验证、AB 测试、定向回滚，必须保证特定用户/设备/地域始终落在同一版本
实操建议：
- 初期别碰 Istio，先用 Spring Cloud Gateway + Nacos 把规则路由跑通，这是 ROI 最高的路径
- 权重策略若真要用，务必搭配监控告警（如 Prometheus 查
http_request_duration_seconds{version="v2"}错误率突增），否则等于裸奔 - 规则路由的判定逻辑一定要可降级：当灰度规则服务不可用时，自动 fallback 到默认版本，而不是报 503
灰度不是加个开关就完事，真正难的是标签在哪一级生成、在哪一级消费、断点在哪一级丢失——这些细节不抠清楚，切分再细也白搭。
