一、为什么要做灰度发布与金丝雀部署？
很多人可能没听过这两个词，但你肯定见过类似的场景：奶茶店新出了一款限定奶茶，会先在1家店试卖一周，销量好再全部门店上线；外卖平台新功能上线，不会直接推给所有商家，先给1%的商家测试，出bug也只会影响1%，不会崩。这就是灰度发布和金丝雀部署的核心逻辑——小范围试验，没问题再扩大范围，本质是降低新功能上线的风险，避免全量上线后出问题导致用户体验崩溃。
1.1 灰度与金丝雀的通俗区别
不用纠结两个词的字面意思，你可以理解为：灰度是按比例（比如10%）给部分用户；金丝雀是更极端的小范围（比如0.1%）试验，就像煤矿工人下矿前会带一只金丝雀，金丝雀死了说明有毒，马上撤人。两者都是为了把风险控制在最小范围。
1.2 这些方式解决什么核心问题
如果你直接全量上线新功能，假设新功能有个隐藏的bug，比如外卖APP的接单功能不能用，所有商家都会受影响，投诉量会爆炸，损失无法挽回。而用灰度的话，哪怕出问题，也只会影响小部分用户，而且能快速切回老版本，不用连夜救火。
二、Zuul API网关的核心作用是什么？
Zuul就像小区门口的门岗，所有进出小区的请求都必须经过他。你不用让每个住户自己拦人、指路，门岗统一处理所有请求：哪个单元是新楼（新版本服务），哪个是老楼（旧版本服务），他都知道，根据用户的取件码（请求特征）指引方向。
2.1 Zuul的核心能力
Zuul自带过滤器功能，能在请求到达业务服务前、后做各种处理，比如拦截请求、修改请求头、转发路由，这正好符合我们做灰度发布的需求——不用改业务服务的代码，只要在Zuul里加个判断逻辑，就能把请求转发到对应的版本服务。
2.2 为什么选Zuul做灰度？
和其他网关比，Zuul的优势是上手快、配置简单，适合中小团队快速落地灰度方案，不用搞太复杂的部署。如果你是刚接触微服务，Zuul是很容易理解的工具，不用一开始就啃大框架。
三、用Zuul实现灰度的核心原理
简单说就是：在请求到达业务服务之前，Zuul先检查请求的某个特征（比如用户ID），按我们定的规则（比如User-ID是奇数走新版本，偶数走老版本），把请求转发到对应的服务实例。
举个最容易理解的例子：你做了一个用户服务，有两个版本，v1是旧功能，v2是带新功能的版本。Zuul作为网关，收到所有请求后，先看请求里的User-ID，如果是1、3、5这样的奇数，就转发到v2；如果是2、4、6这样的偶数，就转发到v1，这样就实现了50%的灰度比例。
四、完整示例落地
我们用单一技术栈做演示，所有内容都不超过Spring Cloud Zuul的范围，不用混合其他工具，上手就能跑。
4.1 技术栈明确
技术栈：Spring Boot 2.7.x + Spring Cloud 2021.0.6 + Zuul 1.4.5
4.2 准备基础服务
你需要启动3个服务：1个Zuul网关（8080端口）、1个老版本用户服务（v1，8081端口）、1个新版本用户服务（v2，8082端口），这里用写死服务地址的方式，不用Eureka，更简单。
4.3 Zuul核心配置（YAML格式，直接复制就能用）
server:
port: 8080 # Zuul网关的端口，所有请求都从这里进入
spring:
application:
name: zuul-gray-gateway
cloud:
zuul:
routes:
# 老版本服务路由，路径匹配/user-v1/**的请求转发到v1
- path: /user-v1/**
serviceId: user-service-v1
# 新版本服务路由，路径匹配/user-v2/**的请求转发到v2
- path: /user-v2/**
serviceId: user-service-v2
# 禁用Eureka，直接用配置的服务地址，简化部署
ribbon:
eureka:
enabled: false
# 老版本服务的实际地址
user-service-v1:
ribbon:
listOfServers: http://localhost:8081
# 新版本服务的实际地址
user-service-v2:
ribbon:
listOfServers: http://localhost:8082
4.4 灰度规则的核心代码（过滤器，带详细注释）
这个过滤器就是Zuul的“小本子”，每次收到请求，先查这个过滤器，决定转发到哪个服务：
import com.netflix.zuul.ZuulFilter;
import com.netflix.zuul.context.RequestContext;
import org.springframework.stereotype.Component;
import javax.servlet.http.HttpServletRequest;
@Component
public class GrayPublishFilter extends ZuulFilter {
// 过滤器类型：pre表示在路由到业务服务之前执行，适合做灰度判断
@Override
public String filterType() {
return "pre";
}
// 过滤器执行顺序，数值越小越优先，这里设为1，确保在其他过滤器之前执行
@Override
public int filterOrder() {
return 1;
}
// 是否启用这个过滤器，设为true，一直生效
@Override
public boolean shouldFilter() {
return true;
}
// 核心逻辑：判断用户属于哪个灰度组，决定转发到哪个服务
@Override
public Object run() {
RequestContext ctx = RequestContext.getCurrentContext();
HttpServletRequest request = ctx.getRequest();
// 从请求头里拿用户ID，方便测试，你也可以换成参数、Cookie等
String userId = request.getHeader("User-Id");
// 灰度规则：User-ID是奇数走新版本v2，偶数走老版本v1（50%灰度）
// 如果你想改成10%灰度，只要把规则改成：Integer.parseInt(userId) % 10 < 1
if (userId != null && Integer.parseInt(userId) % 2 == 1) {
ctx.set("serviceId", "user-service-v2");
} else {
ctx.set("serviceId", "user-service-v1");
}
return null; // 不需要返回值，这里只是做路由判断
}
}
4.5 测试验证
启动三个服务后，用curl命令测试：
# 测试新版本（User-Id=1是奇数），应该返回v2的内容
curl -H "User-Id:1" http://localhost:8080/user-v1/info
# 测试老版本（User-Id=2是偶数），应该返回v1的内容
curl -H "User-Id:2" http://localhost:8080/user-v1/info
如果返回结果不同，说明灰度规则生效了，非常简单。
五、应用场景
5.1 新功能小范围测试
比如你做了一个电商的商品详情页改版，先给10%的流量，看点击率、转化率有没有提升，没问题再全量上线，不用担心里程碑式的改动带来的损失。
5.2 快速回滚兜底
如果新版本上线后发现bug，只要把灰度比例调到0，就能瞬间把所有流量切回老版本，不用停服重启，是金融、电商这种不允许 downtime 的场景的必备方案。
5.3 A/B测试
同一个功能做两个版本，让一半用户看A版，一半看B版，数据化对比哪个效果好，再决定全量用哪个，不用靠拍脑袋做决策。
六、技术优缺点
6.1 优点
- 不用改业务代码，路由逻辑统一在网关处理，业务服务只专注做功能；
- 规则灵活，灰度比例、判断条件随时调整，不用重启服务；
- 成本低，适合中小团队快速落地，不用搞复杂的部署流程；
- 可监控性强，能和Prometheus、Grafana等工具结合，实时看灰度服务的健康度。
6.2 缺点
- Zuul 1是阻塞式架构，高并发下性能不如Spring Cloud Gateway，适合中小系统，大流量场景可能需要替换；
- 如果规则太复杂（比如同时按地区、设备、渠道判断），过滤器的代码会变臃肿，后期维护难度增加。
七、注意事项
7.1 灰度比例要逐步调整
绝对不能一开始就给100%的灰度，要按1%→5%→10%→20%→50%→100%的节奏，每调整一个比例观察24小时，确认没有异常再扩大范围。
7.2 提前准备回滚开关
一定要做一个一键回滚的配置，比如加个全局开关，关闭灰度规则，所有流量切回老版本，不用手动改代码或者重启服务，出问题时能在30秒内恢复。
7.3 做好核心指标监控
要盯着错误率、响应时间、QPS三个核心指标，一旦新版本的错误率超过0.1%，马上停止灰度，排查问题，不要等用户投诉了才发现。
7.4 新老服务接口要兼容
新服务必须完全兼容老服务的接口，比如老服务返回的字段，新服务必须全部返回，不要加新字段导致前端或者其他服务调用出错。
八、文章总结
用Zuul API网关实现灰度发布，是一种低成本、易上手的方案，核心是把判断逻辑放在网关，不用改业务代码，非常适合中小团队的新功能上线、A/B测试等场景。只要注意灰度比例的逐步调整、回滚的及时性、核心指标的监控，就能把新功能上线的风险降到最低，哪怕是刚接触微服务的开发者，也能快速落地这套方案，不用啃复杂的大框架。
Comments