一句话

安全退役旧系统并把用户迁过去：先建替代品、发通告写迁移指南、渐进迁移、最后才删；数据库走 expand/contract。

何时用

• 适合：移除旧系统、API、功能；迁移用户到新实现；生产库改 schema（rename/drop 列零停机）；评估去留。
• 不适合：还没替代品就想先删；确认无人依赖的死代码可直接删。

怎么用

把旧的分组 API 下线，用户迁到新接口，期间不能断服务

1. 先建替代品并验证它真能用，删除是最后一步。
2. 公告加文档：deprecation notice 写清时间线，migration guide 写清怎么搬。
3. 渐进迁移：strangler、adapter、feature flag 三种模式按场景选；数据库 schema 走 expand/contract。
4. 监控旧路径用量，催存量用户迁移。
5. 用量归零才删旧系统，顺手清掉 zombie code。

产出

• deprecation notice、migration guide、迁移用 flag/adapter 代码、最终的删除提交。

要点与坑

• Hyrum's Law：再内部的行为也有人依赖，移除难度和可观察面成正比；退役规划从设计时就开始。
• 区分 compulsory 与 advisory deprecation，强制性的要给 deadline 和手段。
• 旧路径没观测就不许删，不知道还有多少调用就不能动手。

关联

• 上游：addy-api-and-interface-design · 搭配：addy-shipping-and-launch、addy-observability-and-instrumentation
• 所属：00-addy-概览 · 工作流：W6-高风险加固层