Iris框架本身不内置灰度发布能力，必须依赖APISIX等外部网关实现流量分发；在应用层用if判断做灰度会破坏无状态性、导致规则无法热更新、链路不一致且丧失统一治理能力。
Iris 框架本身不内置灰度发布能力，必须依赖外部网关（如 APISIX、Nginx）或服务网格来实现流量分发；直接在 Iris 应用层做路由决策会破坏无状态性、增加耦合、难以统一治理。
为什么不能在 Iris 应用里写 if 判断做灰度
常见误区是想在 iris.Context 中读取 Cookie 或 Header，然后手动 ctx.Redirect() 或调用不同 handler。这会导致：
- 每个 Iris 实例都要重复实现分流逻辑，无法集中管控和动态调整
- 灰度规则变更需重启服务，失去“热更新”能力
- 无法与下游服务（如数据库、缓存、其他微服务）保持链路一致性
- 健康检查、熔断、日志打标等治理能力全部丢失
APISIX + Iris 的标准灰度接入方式
把 Iris 作为普通 upstream 注册进 APISIX，由 APISIX 统一做流量染色与分发。关键步骤如下：
- 为 Iris 旧版本服务启动一个实例，注册为 upstream：
upstream_old，地址如http://10.0.1.10:8080 - 为 Iris 新版本服务启动另一个实例，注册为 upstream：
upstream_new，地址如http://10.0.1.11:8080 - 创建路由，启用
traffic-split插件，按权重分发（例如 90/10） - 若需基于请求头灰度（如
X-Canary: true），在rules.match.vars中配置：["http_x_canary", "==", "true"]
示例路由配置片段（JSON 格式）：
{
"uri": "/api/*",
"plugins": {
"traffic-split": {
"rules": [
{
"match": [
{
"vars": [["http_x_canary", "==", "true"]]
}
],
"weighted_upstreams": [
{"upstream_id": "upstream_new", "weight": 100}
]
},
{
"weighted_upstreams": [
{"upstream_id": "upstream_old", "weight": 90},
{"upstream_id": "upstream_new", "weight": 10}
]
}
]
}
},
"upstream_id": "upstream_old"
}
如何让 Iris 应用感知灰度上下文
灰度决策交给网关后，Iris 应用只需被动接收并透传染色信息，用于日志标记、DB 路由或调用下游灰度服务：
- 从
ctx.GetHeader("X-Canary")或ctx.GetCookie("version")读取标识 - 在调用其他服务时，将该 header 或 cookie 原样带上（避免链路断裂）
- 不要在 Iris 中根据该值改变业务逻辑分支——那属于功能开关（Feature Flag），应交由配置中心管理
例如记录日志时加 tag：log.Info("order created", "canary", ctx.GetHeader("X-Canary"))
容易被忽略的兼容性细节
灰度期间 Iris 新旧版本共存，以下三点必须提前对齐：
- API 响应结构要向后兼容：新版本不能删字段、改类型，否则旧版前端可能解析失败
- 错误码语义需一致：比如
404在旧版表示“商品不存在”，新版不能复用为“库存不足” - 中间件行为不能突变：如 JWT 解析、CORS 策略、Body 大小限制等，应在网关层统一封装，而非分散在各 Iris 实例中
真正的灰度难点从来不在“怎么切流”，而在于“切流之后，整个调用链是否还说得通”。Iris 只是链路上的一环，别让它成为灰度治理的盲区。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
