API 灰度发布设计指南（免费版）
一、它解决什么问题
新版本直接 100% 全量上线，一旦有缺陷，所有用户同时受影响，回滚也已造成损失。
灰度发布（金丝雀发布）：先让一小部分流量进入新版本，用真实流量"试毒"，
指标健康再逐步扩大比例，异常则自动回滚——把新版本的故障爆炸半径控制在 5% 以内。
二、发布流程
新版本部署
│
▼
5% 流量 ──指标对比──► 劣化超阈值 ──► 自动回滚 ROLLBACK
│健康
▼
20% ──► 50% ──► 100% 全量 PROMOTE
每一级都做指标对比，任一级不达标即回滚
三、关键设计规则
| 项 | 含义 | 设计要点 |
|---|---|---|
| 放量阶梯 stages | 灰度比例，常取 5%→20%→50%→100% | 每级停留观察，不连跳 |
| 错误率余量 error_margin | 灰度错误率允许比基线高出的绝对值，常取 1%~2% | 超过即回滚 |
| P99 延迟余量 latency_p99_margin | P99 允许的相对上浮，常取 10% | 防止新版本变慢 |
| 最小样本 min_sample | 判定前灰度必须积累的请求数，常取 100+ | 防小样本误杀：几十个请求里几个错误不代表版本有问题 |
| 目标权重 target_weight | 达到即全量，通常 100% | 全量前最后一级也要指标健康 |
四、三种判定结果
| 判定 | 触发条件 | 动作 |
|---|---|---|
| ROLLBACK（回滚） | 灰度错误率 > 基线 + 余量，或 P99 上浮超余量 | 流量切回基线，撤销新版本，告警 |
| CONTINUE（观察/提量） | 样本不足，或指标健康但未达目标权重 | 样本够后进入下一放量阶梯 |
| PROMOTE（全量） | 指标健康且权重已达 100% | 全量发布，下线旧版本 |
五、落地检查清单
- [ ] 灰度与基线版本可并行、可按比例分流（基于 header/cookie/用户哈希，保证同一用户稳定命中同一版本）
- [ ] 分别统计灰度与基线的调用数、错误数、P99 延迟
- [ ] 设置最小样本，样本不足只观察、不回滚也不全量
- [ ] 错误率、P99 任一越界即自动回滚，回滚动作可自动执行、无需人工等待
- [ ] 回滚后流量 100% 切回基线，并验证基线正常
- [ ] 每一级放量与判定结果有日志/看板，记录指标快照
- [ ] 灰度期间数据库/缓存的兼容性已确认（新旧版本可能共用数据）
六、判定示例
- 灰度 20%、2000 请求 200 错误（10%），基线错误率 1%、余量 2% → 10% > 3%，ROLLBACK
- 灰度 100%、5000 请求错误率 1%、P99 不劣于基线 → PROMOTE
- 灰度 5%、500 请求指标健康、未达目标权重 → CONTINUE，提量到 20%
- 灰度仅 20 请求、10 个错误，但 min_sample=100 → 样本不足，CONTINUE 不回滚
七、硬性规则
- 指标阈值与放量阶梯按业务容错度设定；核心交易链路可从更小比例起步。
- 样本不足 min_sample 不做回滚/全量判定，避免小样本误杀。
- 回滚必须是自动、可验证的，不能依赖人工在故障时手动操作。
- 本指南为设计方法；需要按真实指标自动计算判定，请使用专业版。
