弃用策略

定义如何、何时、为何弃用 — 使退役对用户可预测的规则。

为什么

无成文策略则弃用是临时的：某功能因某人感觉在 minor 中被删，客户端坏。策略使弃用成契约：弃用功能得最小支持窗口（如 6 个月）、编程信号（Deprecation 头/日志警告）、文档化替代、提前沟通的 sunset 日期。这使客户端能规划迁移而非被伏击，且你队能无疚删代码因遵循了策略。策略还防相反失败 — 因无人愿做删者而永留死功能 — 使删除成排程策略驱动事件而非个人决定。

何时使用

首次弃用前写一次策略。应用于每个计划退役的功能/API。

如何做

1. 定支持窗口：弃用到删除最少 6 个月（主要 API 12 个月）
2. 定信号：Deprecation HTTP 头、SDK console.warn、@deprecated JSDoc、changelog 条目
3. 定文档：每次弃用须命名替代并链迁移指南
4. 定沟通：changelog + 邮件注册用户 + 弃用仪表盘
5. 定删除标准：仅 (a) sunset 日期过 且 (b) 用量 <1% 持续 30 天后删
6. 把策略写入 DEPRECATION.md 并从 README 链接
7. 仪表盘跟踪弃用：功能、弃用日期、sunset 日期、当前用量 %

示例

# DEPRECATION.md（放仓库根）
## 策略
- 支持窗口：6 个月（次要 API）、12 个月（主要 API）
- 信号：Deprecation 头 + console.warn + @deprecated JSDoc
- 删除标准：sunset 日期过 且 用量 <1% 持续 30 天

# 弃用仪表盘（每发布跟踪）
| 功能          | 弃用日期   | Sunset     | 用量  | 状态     |
|---------------|-----------|------------|-------|----------|
| /v1/orders    | 2024-06-01| 2024-12-31 | 0.3%  | 可删     |
| legacyAuth()  | 2024-08-15| 2025-02-15 | 5.2%  | 观察     |
| oldExportFmt  | 2024-09-01| 2025-03-01 | 12%   | 通知     |

# 代码信号
/** @deprecated 用 newAuth() 替代 — 2025-02-15 删除 */
export function legacyAuth() {
  console.warn('[deprecated] legacyAuth() 将于 2025-02-15 删除。用 newAuth()。');
  return newAuth();
}

常见问题

⚠无支持窗口 — 功能同发布弃用并删，客户端无迁移时间坏。
⚠弃用不命名替代 — 客户端被告停用 X 却不知用什么。
⚠仅按 sunset 日期删而用量仍 20% — 你坏没见通知的真实用户。

最佳实践

✓删除前须 sunset 日期过且用量 <1% 持续 30 天 — 仅日期坏滞后客户端。
✓每次弃用须命名替代并链迁移指南 — "别用 X" 无 "用 Y" 无用。
✓跟踪弃用仪表盘含每功能用量 % — 可见防过早删并识别遗忘迁移。