弃用 4 阶段 = 无破坏升级

解决什么问题：API 升级 = 用户被破坏—— 弃用 4 阶段让"破坏性变更"有可控路径。

业务问题

真实场景

场景 1：突然删除 API

- 用户依赖某 API
- 你觉得"没人用了"
- 直接删除
- 第二天 N 个用户报错
- 紧急回滚
- 用户信任崩塌

场景 2：渐进弃用

- 标记 deprecated（编译警告）
- 文档说明替代方案
- 监控使用情况
- 6 个月后关闭
- 用户有时间迁移

弃用 4 阶段

阶段 1：标记（Announce）
  - @Deprecated 注解
  - 编译警告
  - 文档说明
  - 邮件/公告

阶段 2：迁移（Migration）
  - 提供迁移指南
  - 提供迁移工具
  - 主动联系重度用户
  - 监控迁移进度

阶段 3：监控（Monitor）
  - 跟踪使用情况（call sites 数量）
  - 找出未迁移用户
  - 内部系统先迁移
  - 给出"还剩 X 个月"

阶段 4：关闭（Turn Off）
  - 设定硬截止日期
  - 删除代码
  - 释放资源

与 Hyrum 定律的关系

Hyrum 定律：所有可观察行为都会被依赖
弃用 = 主动管理"可观察行为"

4 阶段 = 用户的 4 个机会：
  1. 知道（标记）
  2. 学习（迁移）
  3. 适应（监控）
  4. 完成（关闭）

工程实践

决策 1：弃用周期长度

- 内部 API：1-3 个月
- 外部 API：6-18 个月
- 关键基础设施：12-24 个月

决策 2：如何强制迁移

警告级别（递增）：
  1. 编译警告
  2. 运行时警告
  3. 错误日志
  4. 抛出错误（限时）
  5. 删除

关键洞察

1. 弃用是给用户时间——不是删除。
2. 4 阶段 = 4 个沟通机会——别跳过任何一步。
3. 监控是关键——"以为没人用"常常是错的。
4. 删除才是完成——只标记不删 = 技术债。