Deprecation & Migration — 弃用与迁移

入口/出口

• 入口: 需要移除或替换已有功能、API 版本升级、清理废弃代码
• 出口: 迁移计划 + 兼容层（如需要）+ 文档 + 清理
• 指向: 迁移完成后回到正常 build 流程
• 前置加载: CANON.md
• 输出路径: verify-workflow-review

何时不使用

• 只是新增功能，不移除、替换或改变已有行为
• 废弃范围没有使用数据、兼容要求或迁移窗口
• 只是删除本任务中新建且尚未发布的临时代码

核心原则

Code Is a Liability

代码是负债，不是资产。 未使用的代码仍然需要维护、编译、测试、理解。每行代码都有持续成本。删除代码是改善。

Hyrum 法则使删除困难

有足够用户时，每个可观察到的行为都有人依赖。 即使是未文档化的实现细节、错误消息文本、响应字段排序——某处可能有消费者依赖它。

弃用规划从设计时开始

设计 API 时就为未来弃用规划——使用 Feature Flag 或版本化参数，使旧行为可逐步下线。

弃用决策

在宣布弃用之前回答：

1. 有替代方案吗？ 用户迁移到哪里？替代至少和旧方案一样好。
2. 还有多少用户？ 多少人依赖这个 API/功能？实际使用量是多少？
3. 迁移成本被承担了吗？ 谁负责迁移——提供者还是消费者？迁移工具和文档存在吗？
4. 时间线合理吗？ 如果消费者团队需要 6 个月，不给他们 2 周。
5. 紧急回退可能吗？ 如果迁移出问题，可以立即恢复弃用功能吗？

强制 vs 必须弃用

"必须弃用"不是永久的。 如果消费者不迁移，"建议"变为"强制"带日期。

迁移模式

Strangler Pattern（最安全）

新系统逐步接管旧系统功能:
  Phase 1: 新系统 + 旧系统并存（新代码走新路径）
  Phase 2: 逐渐迁移旧路径到新系统
  Phase 3: 旧系统仅剩 5% 流量
  Phase 4: 旧系统完全关闭

不一次性替换。一条条路由/功能逐步迁移。

Adapter Pattern

// 消费者调用 v2 API → v2 handler（当前版本）
// 旧消费者仍调用 v1 API → v1 adapter → 转换请求 → 委托给 v2 handler
// 所有 v1 消费者迁移后 → 删除 v1 adapter
async function v1CreateTaskHandler(req: V1Request): Promise<V1Response> {
  const v2Request = toV2Request(req);      // v1 → v2 转换
  const v2Response = await v2Handler(v2Request);
  return toV1Response(v2Response);          // v2 → v1 转换
}

Feature Flag 迁移

// Flag 控制新旧代码路径
if (await featureFlag.isEnabled('use-new-task-service', userId)) {
  return newTaskService.create(req);  // 新路径
} else {
  return oldTaskService.create(req);  // 旧路径（逐步关闭 flag）
}

迁移决策流程图

需要弃用？
  ├── 突发弃用（安全漏洞、合规要求）
  │   └── 立即下线 + 紧急通知消费者
  └── 渐进弃用
      ├── 多个消费者？
      │   ├── YES → Strangler Pattern（逐个迁移）
      │   └── NO → Adapter 或直接替换
      ├── 需要兼容期？
      │   ├── YES → Feature Flag 控制新旧路径
      │   └── NO → 直接替换 + 版本号大版本升级
      └── 通知 → 设置过期 → 监控使用 → 移除旧代码

反模式修复表

好/坏弃用公告对照

// Bad: 仅注释——无人感知
// @deprecated use newUserService instead
export const oldGetUser = ...

// Good: 运行时警告 + 迁移指引 + 截止日期
export const oldGetUser = (id: string) => {
  console.warn(
    '[DEPRECATED] oldGetUser will be removed in v3.0 (2026-06-01). ' +
    'Migrate to: userService.getUser(id) — see docs/migration/v2-to-v3.md'
  );
  trackDeprecatedUsage('oldGetUser');
  return userService.getUser(id);
};

好弃用公告三要素：

1. 运行时警告 — 每次调用时提醒消费者，不是沉默的注释
2. 迁移指引 — 明确告诉消费者改用什么、怎么改、文档在哪
3. 截止日期 — 给出具体移除时间，不是"未来某天"

Zombie Code 定义

代码是僵尸代码当它：

• 无人维护，但仍在运行
• 有活跃消费者，但 owner 已经离职/转组
• 文档缺失，但行为有人依赖
• 技术上已弃用，但关闭日期无限期推迟

僵尸代码必须消灭。 标注 owner、迁移消费者、设定关闭日期。

常见说辞

红旗 — STOP

• 弃用公告中没有指定替代方案
• 弃用时间线给消费者不合理的短时间（< 1 个迭代）
• 弃用功能被新功能继续调用（"先弃用，然后我们自己也用它"）
• Comments-only 弃用（"// deprecated" 但没日志、没告警、没文档）
• 旧代码直接删除——没有任何兼容期

验证失败处理

人类伙伴信号

以下话语出现时，说明你的弃用流程有缺口：

• "这个 API 什么时候下线？" — 你没设过期日期。每条弃用公告必须有明确截止时间。
• "还有谁在用这个？" — 你没追踪使用量。废弃前必须加监控，数据驱动决策。
• "迁移指南在哪？" — 你没写迁移文档。文档先行，消费者需要指南才能行动。
• "能再宽限几天吗？" — 你的时间线太紧了。重新评估消费者迁移节奏，调整截止日期。
• "我用了新 API 但行为不一样" — 你的替代方案没有完全覆盖旧 API 的行为。补充测试用例对齐。
• "为什么线上还在调旧接口？" — 你的监控没覆盖所有消费者，或弃用通知没到达。加运行时警告。

全部意味着：STOP。回到弃用决策，补齐缺失环节。

输出模板

弃用与迁移完成后应产出以下结构（记录于 ADR 或项目文档中）：

### Deprecation & Migration 记录

**弃用目标**: [API / 功能 / 模块名]
**替代方案**: [新 API / 新功能名 + 迁移路径]
**弃用类型**: [强制 / 必须]
**截止日期**: [YYYY-MM-DD]

**消费者影响评估**:
| 消费者 | 当前调用量 | 迁移状态 | 迁移支持 |
|--------|-----------|----------|----------|
| [团队/服务1] | [N 次/天] | [已迁移 / 未迁移 / 迁移中] | [迁移指南 / 工具 / 无] |

**迁移时间线**:
- Phase 1: [YYYY-MM-DD] — 新旧并存，运行时警告上线
- Phase 2: [YYYY-MM-DD] — 使用量监控确认下降
- Phase 3: [YYYY-MM-DD] — 旧代码关闭/删除

**回退计划**: [hotfix 路径 / feature flag 回退 / git revert 策略]
**已知限制**: [兼容层行为差异 / 监控覆盖缺口 / 未迁移消费者]

验证清单

• 替代方案明确且可用（消费者迁移到此）
• 弃用时间线合理（执行了消费者迁移节奏）
• 实际使用量已验证（日志/指标——不只是猜测）
• 消费者已通知（文档、公告、直接联系）
• 回退计划存在（如果迁移出问题）
• 旧代码清理已完成（compat layer → 删除 → ADR 标记为"废弃"）