如何编写 API 迁移指南(附真实示例)
目录
前提准备
跟着做不需要你是 API 专家,但需要了解以下基础知识:
- REST API 的基本知识:你应该知道什么是 endpoint、请求头的作用,以及 401、404 这类状态码的含义。
- 能看懂 JavaScript:前后对照的代码示例使用了 JavaScript 的
fetch()函数。你不需要实际运行它们,但应该能看懂每段代码做了什么。 - 熟悉 Markdown:迁移指南会用 Markdown 编写,这也是大多数文档站点和 GitHub README 使用的格式。
提示:文中的 Inventory API 是我为本教程创建的示例 API,无需安装或注册。你只需要一个文本编辑器即可。
什么是 API 迁移指南?
API 迁移指南是一份文档,指导开发者如何将代码从一个 API 版本升级到另一个版本。它会说明发生了什么变更、需要更新哪些内容,以及做出这些更改的截止时间。
人们常将迁移指南与更新日志(changelog)和版本发布说明混淆,因为它们都涉及变更。区别在于它们的目的不同。
更新日志记录发生了哪些变更,版本发布说明宣告有什么新功能,而迁移指南则告知开发者因这些变更需要修改代码的哪些部分。
| 更新日志 | 版本发布说明 | 迁移指南 | |
|---|---|---|---|
| 目的 | 记录每个版本的所有变更 | 宣告版本的新功能 | 协助开发者更新代码 |
| 涵盖内容 | 所有变更,无论大小 | 重点功能和新增特性 | 需要开发者采取行动应对的变更 |
| 形式 | 按版本分组的列表 | 简短的摘要或公告 | 附带代码的分步操作指南 |
| 回答的问题 | “变了什么?” | “新增了什么?” | “我该做什么?” |
因此,如果开发者阅读了更新日志后仍不知道该如何修改代码,这就表明你需要一份迁移指南。通常,这种情况发生在版本包含破坏性变更时。
什么算是破坏性变更?
破坏性变更是指对 API 的任何修改,若开发者不做任何调整,就可能导致现有代码停止工作。例如,如果 API 的某项改动导致用户的集成失效,这就是破坏性变更。
正因如此,API 团队通常将破坏性变更发布在新的主版本中,例如从 v1 升级到 v2。许多团队遵循语义化版本控制(SemVer),这是一种编号系统,像 2.4.1 这样的版本号由三部分(主版本、次版本、修订版)组成。当变更会破坏现有代码时,主版本号增加,这就是为什么你会看到 API 从 v1 直接跳到 v2,而不是 v1.1 的原因。
| API 的组成部分 | 破坏性变更 | 非破坏性变更 |
|---|---|---|
| 端点(Endpoint) | 删除某个端点 | 新增一个端点 |
| 字段 | 重命名、删除字段,或改变字段类型(比如数字改成字符串) | 在响应中新增字段 |
| 参数 | 把可选参数改成必填 | 新增一个可选参数 |
| 认证 | 改变开发者传递 API key 的方式,比如从 URL 移到请求头 | 新增一种认证方式,且原有方式仍然可用 |
| 错误 | 改变错误响应的结构,比如文本消息改成对象 | 在现有错误对象中新增字段,比如请求 ID |
| 分页 | 改变结果分页的方式,比如页码改成游标(cursor) | 提高每页返回条数的上限 |
有些变更介于两者之间。比如在响应中新增字段通常不会出问题,但如果应用的配置是拒绝未知字段,也可能因此崩溃。新增错误状态码同样可能让开发者措手不及,因为他们的代码可能只处理了原有的状态码。
拿不准的时候,就把变更当作破坏性变更来处理,并在迁移指南中说明。
什么时候需要迁移指南?
如果某个版本只包含非破坏性变更,那就不需要迁移指南,通常一条 changelog 记录就够了。但只要版本中包含哪怕一个破坏性变更,开发者就需要知道代码里该改什么——这正是迁移指南的作用。
如何为 Inventory API 编写迁移指南
了解了迁移指南是什么、什么时候需要它之后,接下来就该动手写了。本教程的后续部分将使用前面提到的 Inventory API。这是一个示例 API,开发者可以用它列出库存中的商品、查询库存水平,以及增加或减少库存。
库存 API 正从 v1 迁移至 v2,v1 将于 2027 年 3 月 31 日停止服务。我已在 GitHub 仓库中上传了两个版本的参考文档,请并排打开 v1-reference.md 和 v2-reference.md。在第一步中,你将需要频繁对比这两份文档。
第一步:列出并分类所有变更
在开始撰写之前,你需要先整理出两个版本间所有变更的完整清单。任何在此处被遗漏的变更都不会出现在指南中,开发者只有在代码报错时才会发现这些问题。
请先逐节对比两份参考文档。例如,以下代码展示了在两个版本中从某商品库存中移除 5 个单位的相同请求:
# v1
curl -X POST "https://api.example.com/v1/items/itm_204/adjust?api_key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"qty": -5}'
# v2
curl -X POST "https://api.example.com/v2/items/itm_204/adjust" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"quantity": -5}'
仅此一个请求就体现了三处变更:
- 基础 URL 路径由
/v1变更为/v2。 - API 密钥从 URL 参数迁移至
Authorization请求头。 - 字段名
qty更名为quantity。
请像这样通读两份文档,记录下发现的每一处差异,无论其多么微小。
针对实际产品,不要仅依赖文档,因为它们可能存在滞后。同时需查阅更新日志和 Pull Request,并咨询新版本构建的工程师以确认你的清单。如果两个版本都具备 OpenAPI 规范,可以使用 oasdiff 等工具进行对比,并自动标记破坏性变更。
获得完整清单后,将其制表。针对每项变更,记录发生位置、是否破坏兼容性以及受影响群体:
| # | 变更 | 位置 | 破坏性? | 受影响对象 |
|---|---|---|---|---|
| 1 | 基础 URL 由 /v1 变更为 /v2 |
所有端点 | 是 | 所有用户 |
| 2 | API 密钥由查询参数迁移至 Authorization 请求头 |
所有端点 | 是 | 所有用户 |
| 3 | 用 limit 和 cursor 替换 page 和 per_page |
GET /items |
是 | 所有列出物品列表的用户 |
| 4 | 响应中的 qty 重命名为 quantity |
GET /items、GET /items/{id} |
是 | 所有读取库存数量的用户 |
| 5 | 请求体中的 qty 重命名为 quantity |
POST /items/{id}/adjust |
是 | 所有增减库存的用户 |
| 6 | 错误响应从字符串改为包含 code 和 message 的对象 |
所有端点 | 是 | 所有处理错误的用户 |
| 7 | 请求过于频繁时新增 429 错误 |
所有端点 | 按破坏性处理 | 所有高并发请求的用户 |
| 8 | 物品响应中新增 warehouse_id 字段 |
GET /items、GET /items/{id} |
否 | 需要了解库存所在位置的用户 |
| 9 | 请求体中新增可选的 reason 字段 |
POST /items/{id}/adjust |
否 | 需要记录库存变动原因的用户 |
注意 qty 的重命名出现了两次:一次在响应中,一次在请求体里。虽然是同一个重命名,但开发者需要在代码的不同位置进行修改,所以列为两条独立变更。
变更 7 是我前面提到的中间情况的例子。429 错误本身不会破坏任何东西,但不处理它的代码可能以开发者意料之外的方式失败,所以我把它当作破坏性变更。
所有变更都已列出并分类后,你就清楚这份指南需要覆盖哪些内容了。九条变更中有七条需要开发者采取行动,它们将构成指南的主体。
第 2 步:拟定大纲并撰写摘要
接下来要决定的是指南的组织方式。开发者不会像读文章那样从头到尾通读迁移指南,他们只会快速扫描与自己相关的部分,改完就走。所以指南结构应该按照开发者提问的顺序来回答这些问题。
以下是我为 Inventory API 指南使用的大纲:
# 从库存 API v1 迁移到 v2
## 概述
## 时间表
## 破坏性变更
### 基础 URL
### 认证
### 分页
### 字段重命名:qty 改为 quantity
### 错误响应
### 限流
## 新功能
## 迁移检查清单
## 测试迁移效果
## 回滚
概述和时间表放在开头,因为它们回答了每个开发者最先关心的两个问题:“这对我有影响吗?”以及“我有多少时间?”
破坏性变更紧随其后,因为它们要求采取行动;新功能则放在后面,因为开发者可以忽略这些,代码也不会因此出错。检查清单、测试和回滚部分放在最后,因为开发者需要在完成更改后才需要使用它们。
大纲确定后,撰写概述。它应告知开发者发生了什么变化、影响谁,以及截止日期。保持简短,几句话即可。
对于库存 API,内容如下:
# 从库存 API v1 迁移到 v2
## 概述
库存 API v2 改变了认证方式、翻页机制以及错误返回形式。此外,`qty` 字段被重命名为
`quantity`。如果你的代码调用了任何 v1 端点,必须在 **2027 年 3 月 31 日** v1 停止服务之前更新它。
本指南将逐一介绍每个变更,并提供更改前后的代码示例。
## 时间表
| 日期 | 事件 |
|---|---|
| 现在 | v2 已可用。v1 仍然有效,你可以按自己的节奏迁移。 |
| 2027 年 3 月 31 日 | v1 停止工作。对 `/v1` 端点的请求将失败。 |
截止日期以粗体显示,并出现在第一段中。如果开发者只阅读指南中的一句话,那应该是包含日期的一句。
第 3 步:通过前后代码示例记录每个变更
这是指南的核心部分,也是开发者投入时间最多的地方。对于每个破坏性变更,他们希望知道发生了什么变化,以及需要在代码中更新什么。
为保持一致性,使用相同的四个部分记录每个变更:
- 变更内容
- 变更原因(仅在原因对开发者有帮助时说明)
- 前后代码示例
- 你需要做什么
认证变更是一个很好的例子,因为每个使用 API 的开发者都会遇到这个问题:
### 身份认证
**改了什么:** v2 不再接受把 API key 放在查询参数里,改为放在 `Authorization` 请求头中传递。
**为什么改:** URL 里的 API key 可能会出现在服务器日志和浏览器历史记录中,被其他人看到。放进请求头就能避免这种情况。
**改前(v1):**
```javascript
const res = await fetch(`${BASE_URL}/items?api_key=${API_KEY}`);
```
**改后(v2):**
```javascript
const res = await fetch(`${BASE_URL}/items`, {
headers: { Authorization: `Bearer ${API_KEY}` },
});
```
**你需要做什么:** 从所有请求 URL 中移除 `api_key`,把 key 放到 `Authorization` 请求头里。v2 会拒绝以查询参数方式传递的 key。
"为什么改"这一部分只有两句话,但作用很关键。开发者通常不愿意改已经能正常跑的代码,很多人会拖到最后一刻才迁移。当他们看到这个改动能保护自己的 API key 安全时,就有了立刻动手的明确理由。
其余的改动
其他改动沿用同样的格式,但不是每一项都需要这么详细。简单的改动一句话加一行代码就够了;而影响开发者代码结构的改动,则需要完整的改前改后示例。
Inventory API 有些改动很简单,各用一两句话说明即可:
- Base URL:所有端点从
/v1换到了/v2,开发者只需在一个地方更新基础 URL。 qty改名为quantity:开发者需要改掉所有读取响应中该字段、以及在请求体中发送该字段的地方。- 新增字段:响应中的
warehouse_id和 adjust 请求体中的reason都是可选的新增项。它们放在指南的"新功能"部分,因为不使用也不会有任何影响。
分页和错误处理就不一样了。这两项都会改变开发者编写循环和错误处理的方式,所以需要完整的代码示例。
分页
v1 使用页码,开发者循环请求直到最后一页;v2 使用 cursor,开发者持续请求下一页,直到 next_cursor 返回 null:
// v1:页码
let page = 1;
let totalPages;
do {
const res = await fetch(
`${BASE_URL}/items?page=${page}&per_page=100&api_key=${API_KEY}`
);
const body = await res.json();
saveItems(body.data);
totalPages = body.total_pages;
page++;
} while (page <= totalPages);
// v2:游标
let cursor = null;
do {
const query = cursor ? `limit=100&cursor=${cursor}` : "limit=100";
const res = await fetch(`${BASE_URL}/items?${query}`, {
headers: { Authorization: `Bearer ${API_KEY}` },
});
const body = await res.json();
saveItems(body.data);
cursor = body.next_cursor;
} while (cursor);
错误与限流
v1 中 error 是字符串;v2 改为对象,包含 code 和 message,并新增 429 错误,其 Retry-After 响应头告知开发者需等待的秒数。由于两处改动都涉及错误处理,指南可将它们合并为同一个示例说明:
// v1
if (!res.ok) {
const body = await res.json();
console.error(body.error); // "Item not found"
}
// v2
if (!res.ok) {
const { error } = await res.json();
if (error.code === "rate_limited") {
const waitSeconds = Number(res.headers.get("Retry-After"));
// 等待后重试请求
}
console.error(error.message); // "Item not found"
}
至此已覆盖第 1 步列表中的全部变更。所有 Breaking changes 均可在完整指南中查阅。
Step 4:添加迁移检查清单
迁移指南通常不标配检查清单,许多优秀指南也不包含此项。但我仍倾向于在多数情况下添加它,以便开发者掌握已更新与待更新的内容。读完所有变更说明后,他们可通过检查清单快速定位遗漏项,无需回翻正文重新检索。
以下是 Inventory API 指南的检查清单示例:
## 迁移清单
- [ ] 把 base URL 从 `/v1` 改为 `/v2`
- [ ] 把 API key 从 `api_key` 查询参数移到 `Authorization: Bearer` 请求头
- [ ] 用 `limit` 和 `cursor` 替换 `page` 和 `per_page`
- [ ] 删除读取 `total_pages` 的代码
- [ ] 在读取响应的代码中,把 `qty` 改名为 `quantity`
- [ ] 在 adjust 请求体中,把 `qty` 改名为 `quantity`
- [ ] 改为读取 `error.message` 和 `error.code`,而不是 `error`
- [ ] 通过 `Retry-After` 请求头处理 `429` 错误
- [ ] 测试迁移效果(见下文)
- [ ] 语法会把每一项显示成复选框,不过在文档网站上勾选不会保存状态,所以开发者可以把它当作参考清单来用。
自己写清单时,注意以下几点:
- 每项只包含一个操作:每一项都应该是开发者能完成并勾掉的事。"更新分页"这种说法太笼统,所以我把它拆成了替换参数和删除
total_pages代码两项。 - 顺序与指南一致:清单条目按照 Breaking changes 部分的顺序排列,开发者遇到问题时可以直接跳回对应的章节。
- 只列破坏性变更:新增的
warehouse_id和reason字段没出现在清单里,因为开发者不需要对它们做任何改动。 - 测试放在最后:最后一个条目指向测试章节,确保开发者验证一切正常之后,再切换到 v2。
如果迁移只有一两处改动,可以省略清单,否则它只是在重复指南内容。
Step 5: 补充测试与回滚指引
在把 v2 上到生产环境之前,开发者会想确认新代码能正常运行;而如果切换后出了问题,他们也需要一条退路。这一步就是为这两件事准备的。
帮开发者测试迁移
测试章节应该告诉开发者,代码里哪些部分最可能出问题。对 Inventory API 来说,是分页、错误处理和限流,因为这些变化会影响开发者编写逻辑的方式,而不只是改个 URL 或字段名。
由于 v1 和 v2 在截止日期前都能正常使用,开发者可以在两个版本上发送同样的请求并对比结果,这是查漏补缺最简单的方法。
下面是 Inventory API 指南中的测试章节:
## 测试你的迁移
在将生产代码切换到 v2 之前,请确认其行为与 v1 保持一致:
1. **比对完整商品列表。** 在 v1 和 v2 中遍历所有商品,核实商品总数与数量是否一致。
2. **测试末页逻辑。** 确保当 `next_cursor` 为 `null` 时循环停止,且不会请求多余的页面。
3. **测试错误处理。** 请求一个不存在的商品 ID,检查代码是否正确读取了 `error.code`(`item_not_found`)和 `error.message`。
4. **测试库存调整。** 通过 `quantity` 字段增加或减少测试商品的库存,然后获取该商品,检查新数值是否正确。
5. **测试限流机制。** 如果批量发送请求,确保代码在收到 `429` 响应时能等待并重试。
每项测试都聚焦于一个具体变更,并展示正确结果应有的样子。像“测试分页功能”这样模糊的步骤帮不了什么,因为开发者不知道具体该检查什么。
告知开发者如何回滚
即使测试充分,开发者切换后仍可能出现意外。回滚章节要告诉他们在遇到这种情况该怎么做。
对于 Inventory API,回滚是可行的,因为 v1 在 2027 年 3 月 31 日之前一直可用。指南应建议开发者保留 v1 代码,直到对 v2 有十足信心,并通过配置在两个版本间切换,这样回滚就不必重写代码:
## 回滚
v1 在 **2027 年 3 月 31 日**之前保持可用,因此在迁移后如果出现问题,你可以切换回 v1。
为了方便回滚,请在确信 v2 正常工作前保留 v1 代码,并通过配置(如环境变量)在两者间切换,而不是直接编辑代码。2027 年 3 月 31 日之后将无法回滚,因此务必在此截止日期前完成测试。
不要省略最后一句话。开发者需要知道什么时候将无法退回 v1,以便在截止日期前留出足够的测试时间。
步骤 6:发布并宣传指南
指南完成后,将其发布在文档中并告知开发者它的存在。不要指望他们自己能找到。
对于 Inventory API,我会在这几个地方分享它:
- 文档: 在 v1 参考页面上添加一个横幅,链接到该指南。
- 变更日志: 为 v2 添加一条记录,链接到该指南。
你还可以让工程团队在 v1 的响应中加上 Sunset header。这样每次响应都会带上停用日期,错过邮件的开发者也能看到。
指南发布后,还要持续维护。当开发者在支持工单里反复问到同一个问题时,就把答案补充进指南;等 v1 正式停用后,把指南标记为过时,避免新开发者误用。
API 迁移指南常见的错误有哪些?
如果开发者读完迁移指南还是不知道该改什么代码,那这份指南就失败了。以下是导致这种情况的五个常见错误,以及如何避免。
- 只链接 changelog 而不做解释:写一句"详见 changelog"会把理解每个变更对自己代码影响的负担甩给开发者。指南里应该把每个破坏性变更都解释清楚。
- 缺少代码示例:只用文字描述变更是不够的。应该把 v1 和 v2 的代码并排展示,让开发者一眼看出要改什么。
- 截止日期不醒目:如果停用日期埋在指南中间,有些开发者会漏看。把它放在第一段。
- 破坏性变更和非破坏性变更混在一起:把新的可选功能和破坏性变更列在一起,开发者很难分清哪些是必须改的、哪些是可选的。应该分开放在不同章节。
- 缺少测试指引:没有测试指引,开发者只能在切换到新版本、上了生产环境之后才发现问题。要告诉他们该测什么、正确的结果是什么样。
结语
在本教程中,你从头到尾为 Inventory API 编写了一份迁移指南:梳理了 v1 和 v2 之间的所有变更,围绕开发者关心的问题组织内容,用前后代码对比记录每项变更,并附上了检查清单、测试步骤和回滚方案。
这套方法可以套用到你负责的任何 API 上。如果你需要现成的模板,GitHub 和我博客上都有完成的 Inventory API 迁移指南和参考文档。直接沿用其结构,替换成你自己的变更内容即可。