该怎样写一份真正管用的 API 迁移指南

API 迁移指南是那种能把一次不兼容的变更，变成一份清单、而不是一场故障的文档：到底发生了什么变化，该怎么应对，以及截止到什么时候。一条体验日志记录可以用两句话说清楚一次不兼容的变更；而迁移指南才是调用方在那两句话说出”这会破坏你的调用”、而她需要确切知道该改哪里的时候，真正会打开的东西。只发布记录而不配上指南，正是调用方最终从一张支持工单里、而不是从那份本该阻止这一切发生的文档里，才得知这次不兼容变更的原因。

API 迁移指南到底是什么

一份一步一步的文档，把调用方从 API 的旧形态带到新形态，写给那些手头已经有代码需要修改的人看，而不是写给那些还在犹豫要不要采用这个 API 的人看。这个区别很重要：迁移指南默认已经存在一个正在运行的集成、已经有真实的生产流量在跑，所以它必须覆盖回滚、部分迁移，以及怎样判断迁移到底成不成功，而这些都是第一次接入的指南完全不需要处理的问题。

迁移指南通常就夹在最后两者之间：停用通知启动了一个倒计时，而迁移指南则是调用方在这个倒计时结束之前必须遵循的东西。

一次变更什么时候需要迁移指南，而不只是一条体验日志记录

当旧行为和新行为之间不止一步之遥，或者这次变更触及了足够多的调用点，让调用方从一个具体的示例中获得的帮助，远大于只读一段文字描述的时候。什么是不兼容的变更，又该如何发布它完整讲解了判断一次变更是否不兼容的标准；一旦答案是肯定的，第二个问题就变成了，这次修复到底是一行代码的调整，还是一次真正的迁移。一个改了名字的字段，调用方光靠一条体验日志记录就能应付过去。而认证、分页或者错误处理上的变更，几乎总是配得上一份专门的指南，因为正确的替代代码，从一句话的描述里根本看不出来。

一份迁移指南必须包含什么内容

五样东西，而只要漏掉其中任何一样，指南就会变成一个调用方只读一次、然后就转向反复试错的页面。旧代码，按它在真实项目里实际出现的样子展示出来。新代码，用同样的方式展示，而不是用一段抽象的话去描述两者的差异。如果什么都不改，到底会坏在哪里，要直白地说出来，因为”什么都不会坏”本身就是一个常见且合理的答案，但调用方仍然需要明确地听到这句话。一种能验证迁移是否真的成功的方法，比如某个响应字段，或者一个可以检查的状态码。还有一份时间表：旧行为到底什么时候会停止工作，以及在这期间新旧两种形态是否都可用。

## 将货币字段从 float 迁移到 integer (v3.0.0)

之前：
  { "amount": 19.99 }

之后：
  { "amount": 1999 }  // 最小货币单位（分）

发生了什么变化：`amount` 现在是账户货币最小单位下的一个整数。
从 2026 年 10 月 1 日起，把 `amount` 当作 float 来读取的代码，会
读到一个大了 100 倍的数值。

验证方法：迁移之后，一笔 19.99 美元的扣款应该读作
`amount: 1999`，而不是 `amount: 19.99`。

时间表：v2 会继续返回 float，直到 2027 年 1 月 15 日为止。v3 从
上线那一刻起就返回整数。目前两个版本都在正常运行。

这五样东西中的每一样，回答的都是一个调用方本来只能靠猜测、或者只能去问支持团队才能知道答案的问题，而这，正是一份迁移指南真正省下来的成本。

谁应该来写它，又该在什么时候写

设计这次变更的人，就在它被发布的那一刻动手写，而不是靠支持团队一周之后再从工单里把它拼凑出来。做出这个决定的人，才知道旧行为里到底哪些部分本来就不该有人依赖、哪些又只是一种意外形成的约定；而由一个不了解这些背景的人事后补写的指南，往往要么把显而易见的地方解释得过头，要么恰恰漏掉了那个真正会让人栽跟头的边界情况。指南和宣布这次不兼容变更的体验日志记录，理应同时发布，而且记录本身应该链接到指南，而不是把指南的内容重新说一遍。

这和版本管理、以及 API 体验日志之间是什么关系

关系非常直接：迁移指南就是 语义化版本控制，应该怎样配合你的体验日志 里，一条 MAJOR 记录只用一句话概括的那件事的详细版本。体验日志记录说明了这次变更是不兼容的，也大致说明了发生了什么变化；而迁移指南，正是那条记录本该携带的那个链接。API 体验日志：该公开什么内容，又是谁在读它 把迁移指南列为一个 API 维护的五份文档之一，每一份都回答着不同的问题；这一份回答的正是”我到底该怎样真正从 A 迁移到 B”，而它之所以配得上拥有自己的一整个页面，恰恰是因为这个答案对一条体验日志记录来说，通常实在是太长了。

一份迁移指南应该保持发布状态多久

至少要持续到旧行为彻底不可访问为止，理想情况下，之后也应该继续保留。一个忽略了三次停用通知、迟到了十八个月才来迁移的调用方，依然需要这份指南，而在旧行为下线的当天就把它删掉，只会保证那个最需要它的调用方，恰恰找不到它。把它放在一个稳定的网址上，然后更新时间表那部分内容，而不是把整个页面撤下来。Stripe 自己的 升级指南就是这种做法的一个公开范例：只有一个页面，随着 每一次新版本发布持续更新，而不是每个版本各写一份、下一版一上线就立刻过时的独立文档。你自己 的指南也应该放在同样容易被找到的地方，紧挨着调用方本来就在读的文档，而不是被埋进 一个体验日志的归档里。

FAQ

是不是每一次不兼容的变更都需要一份迁移指南? 不是。如果一次变更调用方光靠一条体验日志记录就能自行解决，比如一个改了名字、但替代方案很明显的字段，那就不需要单独的指南。但如果一次变更触及了多个调用点，或者需要一个具体示例才能讲清楚，那就需要。

迁移指南到底应该放在 API 文档旁边，还是应该放进体验日志里? 放在文档旁边，然后从体验日志记录里链接过去。记录是订阅者最先看到的东西；指南则是她一旦决定要采取行动时才需要用到的东西，理应放在调用方本来就已经在用的那份参考资料旁边。

迁移指南和停用通知之间到底有什么区别? 停用通知宣布的是某样东西即将消失，以及截止到什么时候。迁移指南则是关于该怎么应对这件事的具体说明。一份没有链接到迁移指南的停用通知，只是给了调用方一个截止日期，却没有告诉她该怎么在这个日期之前完成迁移。

在迁移窗口期内，旧行为和新行为是不是都应该被记录下来? 是的，如果可能的话最好放在同一个页面上，这样调用方就能确切看到到底发生了什么变化，而不必自己从两份分别在不同时间写成的文档里，把这些信息拼凑起来。

本文的技术内容未经独立审核。如有错误，请告诉我们，我们会更正。

changeloop 相关页面： 开发者文档, changelog 示例