Sunset 时间线

沟通弃用到删除的时间线，使客户端能自信规划迁移。

为什么

sunset 日期无时间线是威胁非计划 — 客户端知悬崖来却不知如何下。时间线把窗口分阶段带具体动作：公告（弃用 + 文档）、提醒（升级警告 + 直接联系）、限制（限流或降级）、删除（410 Gone）。每阶段给滞后客户端另一次迁移机会，且进展可见故无人可称意外。时间线还逼你队做沟通工作 — 无阶段则"12 月删"变"12 月删了且没邮件任何人"。时间线是受管退役与宕机之差。

何时使用

每次弃用。弃用时定时间线并在 changelog + 头中沟通。

如何做

1. 公告（0 月）：弃用信号 + changelog + 文档 + 邮件注册用户
2. 提醒（3 月）：升级到每次调用 log.warn + 按 API key 直接邮件 top 调用者
3. 限制（5 月）：限流弃用端点（如正常的 10%）推迁移
4. 删除（6 月）：返 410 Gone 带 Link 头到替代 + 迁移指南
5. 410 保一发布周期使客户端得清晰错误非 404
6. 每阶段转换在 changelog 和弃用仪表盘沟通
7. 若 5 月时用量仍 >5% 则延时间线而非坏客户端 — 沟通延期

示例

# /v1/orders 的 sunset 时间线（6 个月窗口）
# 0 月（2024-06-01）：公告
res.set('Deprecation', 'true');
res.set('Sunset', 'Sat, 31 Dec 2024 GMT');
res.set('Link', '</v2/orders>; rel="successor-version"');
# changelog："弃用 /v1/orders — 用 /v2/orders。2024-12-31 删。"

# 3 月（2024-09-01）：提醒
logger.warn({ key: req.apiKey }, 'v1/orders 弃用 — 迁到 v2');
# 邮件 top 100 调用者按用量

# 5 月（2024-11-01）：限制
if (req.path.startsWith('/v1/')) {
  // 限流 10 请求/分钟（推迁移）
  await rateLimit(req.apiKey, 'v1-deprecated', 10, 60);
}

# 6 月（2024-12-01）：删除
app.use('/v1/orders', (req, res) => {
  res.status(410).set('Link', '</v2/orders>; rel="successor-version"').json({
    error: 'gone', message: '用 /v2/orders — 见 docs/migrate-v1-v2.md'
  });
});

常见问题

⚠从弃用直跳 410 无中间阶段 — 客户端无警告升级感被伏击。
⚠sunset 日期用量仍高却不延时间线 — 你为任意截止坏真实用户。
⚠立即删 410 返 404 — 客户端分不清"删"与"从不存在"浪费时间调试。

最佳实践

✓用 4 阶段时间线：公告、提醒、限制、删除 — 每阶段给滞后者另一次迁移机会。
✓5 月时用量仍 >5% 则延 sunset 日期 — 为日期坏客户端是假经济。
✓删除后保 410 Gone 响应（带 Link 到替代）一发布周期 — 这是最清晰的错误。