迁移路径

提供从弃用物到替代的具体可复制粘贴路径。

为什么

告诉用户"迁到 v2"无迁移路径是告诉他们做无薪工作无地图 — 多数不会，你在 sunset 坏他们。迁移路径是显示确切 diff 的文档：旧调用、新调用、行为差异、做机械部分的 codemod 或脚本。路径须具体到用户 10 分钟内无需读你源码即可跟。最佳迁移路径含自动 codemod 使用户跑一命令即完 — 这把迁移从多日项目变 5 分钟任务，是你驱动新 API 采用的最高杠杆事。

何时使用

每次弃用。发弃用信号前写迁移路径。

如何做

1. 写迁移指南文档：docs/migrate-<旧>-<新>.md
2. 每个改调用显示前后 — 确切代码非散文
3. 列每个行为差异（响应形状、错误码、副作用）— 惊吓
4. 若变更机械则提供 codemod：npx @your-scope/migrate-v1-to-v2
5. 若有用提供兼容 shim：薄适配器映射旧调用到新，供渐进迁移
6. 含验证步：用户如何确认迁移成功（测试、响应 diff）
7. 从弃用头、changelog、每沟通渠道链接迁移指南

示例

# docs/migrate-v1-v2.md
## GET /v1/orders -> GET /v2/orders

### 前
const orders = await fetch('/v1/orders').then(r => r.json());
// orders = { items: [...], total: 5 }
const list = orders.items;

### 后
const res = await fetch('/v2/orders');
const orders = await res.json();
// orders = [...] （直接数组）
const list = orders;
const total = parseInt(res.headers.get('X-Total-Count'));

### 行为差异
- 响应是数组非 { items, total }
- total 在 X-Total-Count 头非 body
- 404 现返 { error: "not_found" } 而非 "Not Found" 字符串

### Codemod（自动）
npx @ez4code/migrate-v1-to-v2 src/
# 重写：fetch('/v1/orders') -> fetch('/v2/orders')
#       res.items -> res
#       res.total -> parseInt(res.headers.get('X-Total-Count'))

### 验证
# 跑测试套件；codemod 保行为。
# diff 样本响应：curl /v1/orders vs /v2/orders（shim 后）

常见问题

⚠迁移指南说"用 v2"无前后 — 用户须读两 API 文档并自己 diff。
⚠机械变更无 codemod — 用户手改 200 调用点引入拼写并怪你 API。
⚠不文档化行为差异 — 用户迁移、测试过，然后 404 错误形状变更在生产坏其错误处理。

最佳实践

✓每个改调用显示确切前后代码 — 散文非迁移路径，可复制粘贴代码是。
✓任何机械变更提供 codemod — 一命令 vs 200 手改是迁移与放弃之差。
✓文档化每个行为差异（错误形状、副作用、默认）— 惊吓是测试过后坏生产的东西。