📚 课程目录第3章弃用策略设计

3. 弃用策略设计：通知机制、时间线规划与灰度发布

API 弃用不是一次性的技术操作，而是一套面向消费者的沟通与风险控制流程。本章围绕三个核心维度展开：通知机制确保信息触达，时间线规划提供可预期的迁移窗口，灰度发布与金丝雀发布降低实际切换风险。三者共同构成弃用策略的骨架。

3.1 弃用通知机制

通知机制的目标是让每个 API 消费者在正确的时间、通过正确的渠道、收到可执行的信息。通知渠道与消息内容需根据消费者类型分层设计。

通知渠道	适用场景	触达时效	推荐内容
HTTP 响应头（Sunset / Deprecation）	所有在线调用	实时	弃用时间、迁移文档链接
开发者门户公告	注册开发者	即时	详细变更日志、迁移指南
邮件通知	企业级消费者	24 小时内	个性化迁移计划、SLA 影响说明
Webhook 推送	配置了回调的合作伙伴	实时	结构化弃用事件 payload
SDK / CLI 警告日志	使用官方 SDK 的开发者	运行时	弃用代码位置、替代 API 建议

最佳实践：Sunset 响应头是 RFC 8594 标准字段，建议在所有弃用 API 的响应中强制添加。格式示例：Sunset: Sat, 31 Dec 2025 23:59:59 GMT。配合 Link 头指向迁移文档，可实现零配置的消费者自动感知。

3.2 弃用时间线规划

时间线是弃用策略的节奏控制器。标准弃用周期通常包含四个阶段，每个阶段对应不同的消费者行为要求。

公告期（Day 0 – Day 30）：发布弃用声明，启动通知渠道，停止新消费者注册旧 API。
并行期（Day 30 – Day 90）：旧 API 保持全功能运行，新 API 上线，消费者可灰度切换。
降级期（Day 90 – Day 180）：旧 API 进入维护模式，仅修复安全漏洞，返回降级响应头。
关停期（Day 180+）：旧 API 返回 410 Gone，DNS 或网关层彻底移除路由。

  时间线参数化建议：将各阶段时长设计为可配置变量（announcement_days、parallel_days、degradation_days），通过配置中心动态调整。对于重大版本（v1 → v2），建议并行期不少于 90 天；对于内部微服务接口，可缩短至 30 天。

3.3 灰度发布与金丝雀发布

灰度发布和金丝雀发布是两种渐进式流量切换策略，用于在弃用迁移过程中最小化爆炸半径。两者核心区别在于流量切分粒度和回滚速度。

特性	灰度发布	金丝雀发布
流量切分方式	按百分比（5% → 20% → 50% → 100%）	按特定标签（用户 ID、地域、客户端版本）
回滚速度	分钟级（调整权重即可）	秒级（移除金丝雀路由规则）
监控要求	聚合指标（P99 延迟、错误率）	金丝雀组与基线组实时对比
适用阶段	并行期大规模验证	降级期高风险变更验证
消费者感知	无感知（随机分配）	可能感知（特定群体固定路由）

关键风险：金丝雀发布中，如果金丝雀组与基线组共享同一数据库或下游依赖，可能出现“噪声干扰”——金丝雀组的错误可能由基线组的慢查询引发。务必为金丝雀组配置独立的监控仪表盘和告警阈值。

3.4 自动化驱动的回滚触发条件

灰度与金丝雀发布必须绑定自动化回滚条件，否则失去风险控制意义。以下为推荐的回滚触发阈值模板：

# 回滚策略配置示例（YAML）
rollback:
  enabled: true
  cooldown_seconds: 120
  triggers:
    - metric: "http_request_error_rate"
      threshold: 0.05        # 5% 错误率
      window_seconds: 60
      comparison: ">="
    - metric: "p99_latency_ms"
      threshold: 2000        # 2 秒
      window_seconds: 120
      comparison: ">="
    - metric: "active_connections"
      threshold: 0.8         # 连接数下降 20%
      window_seconds: 300
      comparison: "<="
  action: "immediate_rollback"   # 可选：gradual_rollback / immediate_rollback
  notification:
    - channel: "pagerduty"
      severity: "critical"
    - channel: "slack"
      severity: "warning"

自动化回滚的幂等性设计：回滚操作本身必须是幂等的——多次触发回滚不应导致状态不一致。建议在回滚脚本中先检查当前路由权重，若已处于全量旧 API 状态则直接跳过。同时记录每次回滚的 rollback_id 和 trigger_reason 到审计日志。

3.5 策略组合矩阵

实际项目中，通知机制、时间线、灰度策略需要组合使用。以下矩阵展示了不同消费者类型对应的推荐策略组合：

消费者类型	通知渠道	时间线长度	发布策略	回滚优先级
内部微服务	HTTP 头 + 日志	30 天	金丝雀（按服务名）	高
合作伙伴 API	邮件 + 门户公告	90 天	灰度（按百分比）	中
公共开放 API	全渠道 + Sunset 头	180 天	灰度（按地域 + 百分比）	高
SDK 消费者	SDK 警告 + 文档	120 天	金丝雀（按 SDK 版本）	中

弃用策略设计的核心原则是：通知可追溯、时间线可预期、切换可回滚。下一层将进入具体的迁移模板实现，把策略转化为可执行的自动化流水线。