deprecation-and-migration

弃用与迁移

概览

代码是一种负债，不是资产。每一行代码都有持续维护成本：要修 bug、要升级依赖、要打安全补丁、还要让新工程师看懂。弃用，是把已经不再值得维护的代码移除出去的纪律；迁移，则是把用户安全地从旧东西带到新东西上的过程。

大多数工程组织都很擅长构建新东西，但很少真正擅长删除旧东西。这个 skill 就是为了解决这个缺口。

何时使用

• 用新系统、API 或库替换旧系统
• 下线一个已经不再需要的功能
• 合并重复实现
• 移除“没人负责但所有人都依赖”的死而不僵代码
• 为新系统规划完整生命周期，也就是在设计阶段就考虑弃用
• 判断是继续维护遗留系统，还是投入迁移

核心原则

代码是负债

每一行代码都有持续成本：需要测试、需要文档、需要安全补丁、需要依赖升级，也会增加附近所有人的心智负担。代码的价值不在“它存在”，而在它提供的功能。如果同样的功能可以用更少的代码、更低的复杂度或更好的抽象提供出来，那么旧代码就应该被移除。

Hyrum's Law 让移除变难

只要用户足够多，系统中每一个可观察行为都会被依赖上，包括 bug、时序怪癖和没写文档的副作用。这就是为什么弃用不能只发公告，还必须做主动迁移。因为用户依赖的往往不只是“功能名义上该做什么”，还包括替代品未必复刻的那些细节。

弃用规划应该从设计时开始

在构建一个新系统时，就该问一句：“如果 3 年后要把它删掉，该怎么删？”
有清晰接口、feature flag 和小暴露面的系统，远比到处泄露实现细节的系统更容易弃用。

做弃用决策前要回答什么

在弃用任何东西前，先回答下面的问题：

1. Does this system still provide unique value?
   → If yes, maintain it. If no, proceed.

2. How many users/consumers depend on it?
   → Quantify the migration scope.

3. Does a replacement exist?
   → If no, build the replacement first. Don't deprecate without an alternative.

4. What's the migration cost for each consumer?
   → If trivially automated, do it. If manual and high-effort, weigh against maintenance cost.

5. What's the ongoing maintenance cost of NOT deprecating?
   → Security risk, engineer time, opportunity cost of complexity.

强制弃用 vs 建议弃用

类型	适用场景	机制
Advisory	迁移是可选的，旧系统仍稳定	警告、文档、提醒，由用户按自己的节奏迁
Compulsory	旧系统存在安全问题、阻碍进展，或维护成本已不可接受	明确截止时间，到期移除，并提供迁移工具

默认优先 Advisory。 只有当风险或维护成本足以 justify 强制迁移时，才用 Compulsory。并且强制弃用必须配套迁移工具、迁移文档和支持，不能只宣布一个最后期限。

迁移流程

步骤 1：先把替代品建出来

没有可用替代品，就不要宣布弃用。替代品至少要满足：

• 覆盖旧系统的所有关键用例
• 带有文档和迁移指南
• 已在生产中被验证，不是理论上“更好”

步骤 2：公告并文档化

## Deprecation Notice: OldService

**Status:** Deprecated as of 2025-03-01
**Replacement:** NewService (see migration guide below)
**Removal date:** Advisory — no hard deadline yet
**Reason:** OldService requires manual scaling and lacks observability.
            NewService handles both automatically.

### Migration Guide
1. Replace `import { client } from 'old-service'` with `import { client } from 'new-service'`
2. Update configuration (see examples below)
3. Run the migration verification script: `npx migrate-check`