← 文章 / 编程开发
freeCodeCamp 1天前 · 2026-11-21 06:28:43 · 7 阅读

如何编写 API 迁移指南(附真实示例)

API 发布新版本后,每个使用它的开发者都得更新自己的代码。如果他们只看到一条更新日志写着“分页改用游标”,那就只能自己摸索怎么改。有的人能改对,有的人可能就不行了。 这就是为什么开发者需要一份 API 迁移指南。它告诉他们发生了什么变化、代码里需要更新哪些地方,以及有多长的迁移时间。 在本教程中,你将学习如何从头到尾编写一份 API 迁移指南。我们会用一个从 v1 升级到 v2 的示例 Inventory API,一起完成这份指南。学完之后,你不仅会得到一份完整的指南,还能拿到一个可以复用到其他 API 上的模板结构。 本教程面向技术写作者、为自己 API 写文档的开发者,以及需要向其他开发者解释 API 变更的 DevRel 人员。

目录

前提准备

跟着做不需要你是 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 步:通过前后代码示例记录每个变更

这是指南的核心部分,也是开发者投入时间最多的地方。对于每个破坏性变更,他们希望知道发生了什么变化,以及需要在代码中更新什么。

为保持一致性,使用相同的四个部分记录每个变更:

  1. 变更内容
  2. 变更原因(仅在原因对开发者有帮助时说明)
  3. 前后代码示例
  4. 你需要做什么

认证变更是一个很好的例子,因为每个使用 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 的开发者,然后在截止日期前再发一两次提醒。
  • 你还可以让工程团队在 v1 的响应中加上 Sunset header。这样每次响应都会带上停用日期,错过邮件的开发者也能看到。

    指南发布后,还要持续维护。当开发者在支持工单里反复问到同一个问题时,就把答案补充进指南;等 v1 正式停用后,把指南标记为过时,避免新开发者误用。

    API 迁移指南常见的错误有哪些?

    如果开发者读完迁移指南还是不知道该改什么代码,那这份指南就失败了。以下是导致这种情况的五个常见错误,以及如何避免。

    • 只链接 changelog 而不做解释:写一句"详见 changelog"会把理解每个变更对自己代码影响的负担甩给开发者。指南里应该把每个破坏性变更都解释清楚。
    • 缺少代码示例:只用文字描述变更是不够的。应该把 v1 和 v2 的代码并排展示,让开发者一眼看出要改什么。
    • 截止日期不醒目:如果停用日期埋在指南中间,有些开发者会漏看。把它放在第一段。
    • 破坏性变更和非破坏性变更混在一起:把新的可选功能和破坏性变更列在一起,开发者很难分清哪些是必须改的、哪些是可选的。应该分开放在不同章节。
    • 缺少测试指引:没有测试指引,开发者只能在切换到新版本、上了生产环境之后才发现问题。要告诉他们该测什么、正确的结果是什么样。

    结语

    在本教程中,你从头到尾为 Inventory API 编写了一份迁移指南:梳理了 v1 和 v2 之间的所有变更,围绕开发者关心的问题组织内容,用前后代码对比记录每项变更,并附上了检查清单、测试步骤和回滚方案。

    这套方法可以套用到你负责的任何 API 上。如果你需要现成的模板,GitHub 和我博客上都有完成的 Inventory API 迁移指南和参考文档。直接沿用其结构,替换成你自己的变更内容即可。

    如果这篇文章对你有帮助,我在LinkedIn和X上分享技术写作和文档方面的经验,欢迎与我建立联系。

    原始来源: freeCodeCamp

    评论 (0)