AB
AiBoss
チュートリアル

为 API 大版本升级编写迁移指南:从变更清单到可执行步骤

チュートリアル

为 API 大版本升级编写迁移指南:从变更清单到可执行步骤

API 发布新版本时,只给一条变更日志往往不够,开发者需要一份能照着改代码的迁移指南。本文以示例 Inventory API 从 v1 升级到 v2 为例,讲清如何列出并分类全部变更、判断哪些属于破坏性变更、按开发者阅读顺序组织文档结构,并为每项变更写出前后对照代码、时间线与迁移清单。

API 发布新的大版本时,所有调用它的代码都得跟着改。如果团队只丢出一条「分页改成游标了」的变更日志,开发者就得自己猜要动哪些地方:有人猜对了,有人改到一半才发现漏了鉴权方式。迁移指南要解决的就是这个问题——它把「改了什么、代码里要改哪里、还有多长时间」一次讲清楚。这篇教程面向技术文档作者、需要为自己维护的 API 写文档的开发者,以及要向其他开发者解释接口变化的 DevRel 人员,用一个示例 Inventory API 从 v1 升级到 v2 的过程,从头到尾写出一份可复用的迁移指南。

准备工作

写迁移指南不需要你是 API 专家,但下面几项基础要具备,否则很难判断哪些变化会影响调用方。

  • REST API 基础:知道什么是端点(endpoint)、请求头起什么作用、401 和 404 这类状态码分别代表什么。
  • 能读懂 JavaScript:本文的前后对照示例使用 fetch()。不需要实际运行,但要能看出每段代码在做什么。
  • 熟悉 Markdown:迁移指南用 Markdown 写,大多数文档站点和 GitHub README 都用这个格式。

本文使用的 Inventory API 是教学用的示例接口,不需要安装任何东西,也不需要注册账号,一个文本编辑器就够了。它提供三类能力:列出库存条目、查询库存数量、增加或减少库存。v1 将在 2027 年 3 月 31 日停止工作,v2 已经可用。两个版本的参考文档需要并排打开对照阅读,第一步会反复用到。

如果要在真实产品上做这件事,除了参考文档,还要把变更日志、合并请求一并翻一遍,并找负责新版本的工程师确认清单——文档可能滞后,漏掉的变化最终会以「用户代码报错」的形式暴露出来。

迁移指南和变更日志有什么区别

这三类文档经常被混为一谈,因为它们都在讲「变化」,但用途完全不同。

文档类型用途覆盖范围回答的问题
变更日志(changelog)记录每个版本的所有改动大大小小的全部变化改了什么?
发布说明(release notes)宣告本次发布的新内容重点功能与新特性新增了什么?
迁移指南帮开发者更新自己的代码需要开发者动手的变化我需要做什么?

判断标准很直接:如果开发者读完变更日志,仍然不知道自己的代码要改哪里,那就说明需要一份迁移指南。这种情况通常出现在发布中包含破坏性变更的时候。

什么算破坏性变更

破坏性变更指任何可能让现有代码在开发者什么都没改的情况下失效的改动。正因为如此,API 团队通常把破坏性变更放进新的主版本号里,比如从 v1 跳到 v2。很多团队遵循语义化版本(SemVer),像 2.4.1 这样的版本号由主版本、次版本、补丁三部分组成;主版本号在改动会破坏现有代码时才递增,所以看到的是 v1 直接到 v2,而不是 v1.1。

API 组成部分破坏性变更非破坏性变更
端点删除某个端点新增端点
字段重命名字段、删除字段、改变字段类型(例如数字变成字符串)在响应中新增字段
参数把可选参数改为必填新增可选参数
鉴权改变 API 密钥的传递方式,例如从 URL 移到请求头新增一种鉴权方式,同时旧方式仍然可用
错误改变错误响应的结构,例如从纯文本消息变成对象在现有错误对象中新增字段,例如请求 ID
分页改变结果分页方式,例如页码分页变成游标分页提高每页条数上限

有些改动介于两者之间。比如在响应中新增字段,多数情况下不会出问题,但那些配置成拒绝未知字段的应用会因此报错;新增一个错误状态码,也可能让只处理旧状态码的代码措手不及。拿不准的时候,按破坏性变更处理,并在指南里覆盖它。

如果一次发布只有非破坏性变更,那就不需要迁移指南,一条变更日志条目通常足够。只要发布里出现哪怕一项破坏性变更,开发者就需要知道代码要改什么,这时才需要写迁移指南。

操作步骤

第一步:列出并分类所有变更

动笔之前,先把两个版本之间的全部差异列出来。这一步漏掉的变更,指南里就不会出现,开发者只能等代码报错时才发现。

做法是逐节对照两份参考文档。下面同一个请求——从某个条目中减少 5 个单位库存——在两个版本里的写法:

# v1
curl -X POST "https://api.example.com/v1/items/ITEM_ID/adjust?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"qty": -5}'

# v2
curl -X POST "https://api.example.com/v2/items/ITEM_ID/adjust" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity": -5}'

一个请求就暴露出三处变化:基础 URL 从 /v1 变成 /v2;API 密钥从 URL 查询参数移到了 Authorization 请求头;请求体里的 qty 改名为 quantity。

照这个方式把两份文档过一遍,把每一处差异都记下来,再小也不要放过。如果两个版本都提供 OpenAPI 规范,可以用 oasdiff 这类工具自动比对并标出破坏性变更,但工具结果仍要人工核对。

清单整理成表格,每行记录:变更内容、发生位置、是否破坏性、影响谁。

#变更位置破坏性影响对象
1基础 URL 从 /v1 改为 /v2所有端点是所有人
2API 密钥从查询参数移到 Authorization 请求头所有端点是所有人
3page 与 per_page 被 limit 与 cursor 取代GET /items是所有列出条目的人
4响应中 qty 改名为 quantityGET /items、GET /items/{id}是所有读取库存数量的人
5请求体中 qty 改名为 quantityPOST /items/{id}/adjust是所有增减库存的人
6错误响应从字符串改为包含 code 与 message 的对象所有端点是所有处理错误的人
7请求过多时新增 429 错误所有端点按是处理所有高频请求的人
8条目响应中新增 warehouse_id 字段GET /items、GET /items/{id}否想知道库存所在仓库的人
9请求体中新增可选 reason 字段POST /items/{id}/adjust否想记录库存变动原因的人

注意第 4 和第 5 行是同一个改名,但一个在响应里、一个在请求体里,开发者修改的是代码的不同位置,所以要拆成两条记录。第 7 行就是前面说的中间情况:429 本身不会破坏什么,但不处理它的代码会以开发者意想不到的方式失败,因此按破坏性变更处理。

九项变更里有七项需要开发者动手,它们构成指南的主体;剩下两项属于新特性,可以单独成节,不写也不会让代码出错。

第二步:搭结构、写摘要

开发者不会像读文章一样从头读到尾。他们扫一眼,找到与自己相关的部分,改完就走。所以结构要按他们提问的顺序来组织。

# 从 Inventory API v1 迁移到 v2

## 摘要
## 时间线
## 破坏性变更
### 基础 URL
### 鉴权
### 分页
### 字段改名:qty 改为 quantity
### 错误响应
### 速率限制
## 新特性
## 迁移清单
## 测试迁移结果
## 回滚

摘要和时间线放最前,因为它们回答开发者最先关心的两个问题:「这影响我吗?」「我还有多久?」破坏性变更紧随其后,因为需要动手;新特性放在破坏性变更之后,因为开发者可以忽略它们而代码不会坏。清单、测试和回滚放在最后,因为开发者改完代码才用得上。

摘要用几句话讲清改了什么、影响谁、截止日期是什么时候:

## 摘要

Inventory API v2 改变了鉴权方式、条目分页方式和错误返回格式,
并把 `qty` 字段改名为 `quantity`。

如果你的代码调用了任何 v1 端点,需要在 **2027 年 3 月 31 日** 之前完成更新,
届时 v1 将停止工作。

本指南逐项说明每处变化,并给出修改前后的代码对照。

时间线用表格呈现,把「现在」和「截止日」两个节点写清楚:

## 时间线

| 日期 | 会发生什么 |
|---|---|
| 现在 | v2 已可用,v1 仍正常工作,可以按自己的节奏迁移。 |
| 2027 年 3 月 31 日 | v1 停止工作,发往 `/v1` 端点的请求将失败。 |

截止日期要加粗,并且出现在第一段里。如果开发者整篇指南只读一句话,那句话应该带着日期。

第三步:为每项变更写前后对照代码

这是指南的主体,也是开发者停留最久的部分。对每一项破坏性变更,他们想知道两件事:变了什么,代码里要改哪里。为了让每节读起来一致,统一用四个小节来写:

  • 变了什么:一句话说清改动本身。
  • 为什么改:只在原因能帮开发者下决心时写。
  • 修改前后代码:可对照的片段。
  • 你需要做什么:明确的动作清单。

鉴权变化是个好例子,因为每个使用该 API 的开发者都会遇到:

### 鉴权

**变了什么:** v2 不再接受把 API 密钥作为查询参数传递,
改为放在 `Authorization` 请求头里。

**为什么改:** URL 里的 API 密钥可能进入服务器日志和浏览器历史记录,
被其他人看到。放在请求头里可以避开这些位置。

**修改前(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`,
改为在 `Authorization` 请求头中发送密钥。v2 会拒绝以查询参数形式传入的密钥。

「为什么改」只有两句话,但作用不小。开发者不喜欢改动已经能跑的代码,很多人会拖到最后一刻才迁移;当他们看到这项改动是为了保护自己的密钥,就有了立刻动手的理由。

其余几项按同样格式展开。分页这一项要写清旧参数与新参数的对应关系,以及游标从哪里取:

### 分页

**变了什么:** 列表端点不再使用 `page` 和 `per_page`,
改为 `limit` 指定每页条数、`cursor` 指定从哪一条之后继续。

**修改前(v1):**

```javascript
const res = await fetch(`${BASE_URL}/items?page=2&per_page=50`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
```

**修改后(v2):**

```javascript
const res = await fetch(`${BASE_URL}/items?limit=50&cursor=${nextCursor}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await res.json();
const nextCursor = data.next_cursor; // 为 null 表示没有下一页
```

**你需要做什么:** 把 `per_page` 换成 `limit`,删除 `page` 参数;
首次请求不传 `cursor`,之后每次用上一次响应里的 `next_cursor` 继续,
直到它为 `null` 为止。

字段改名要分别处理响应侧和请求侧,因为开发者改的是不同位置的代码:

### 字段改名:qty 改为 quantity

**变了什么:** 请求体和响应中的 `qty` 都改名为 `quantity`,含义不变。

**修改前(v1):**

```javascript
const res = await fetch(`${BASE_URL}/items/ITEM_ID/adjust`, {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ qty: -5 }),
});
const item = await res.json();
console.log(item.qty);
```

**修改后(v2):**

```javascript
const res = await fetch(`${BASE_URL}/items/ITEM_ID/adjust`, {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ quantity: -5 }),
});
const item = await res.json();
console.log(item.quantity);
```

**你需要做什么:** 请求体里发送 `quantity`,读取响应时取 `quantity`。
两处都要改,只改一处仍然会出错。

错误响应结构变化要给出新旧两种返回的对比,并说明如何从对象里取信息:

### 错误响应

**变了什么:** 错误响应从一段字符串改为包含 `code` 和 `message` 的对象。

**修改前(v1):**

```json
{ "error": "Item not found" }
```

**修改后(v2):**

```json
{ "error": { "code": "item_not_found", "message": "Item not found" } }
```

**你需要做什么:** 读取 `error.code` 做程序判断,读取 `error.message` 展示给用户。
不要再把 `error` 当作字符串直接拼接或比较。

速率限制这一项要说明 429 的含义,以及建议的处理方式:

### 速率限制

**变了什么:** 请求过于频繁时,v2 会返回 429 状态码。

**你需要做什么:** 在请求逻辑中处理 429,采用退避后重试的方式,
不要立即原样重发。批量拉取数据时控制并发数量。

非破坏性的新特性单独成节,写清字段名和用途即可,不需要前后对照代码,但要明确告诉读者「不改也不会坏」:

## 新特性

- 条目响应新增 `warehouse_id`,表示库存所在仓库。
- 调整库存的请求体新增可选字段 `reason`,用于记录变动原因。

这两项都是新增内容,不修改现有代码也能继续工作。

第四步:写迁移清单、测试与回滚

指南末尾给出一份可以逐项打勾的清单,把前面所有「你需要做什么」压缩成动作条目,方便开发者对照自己的代码库检查:

## 迁移清单

- [ ] 把所有请求的基础 URL 从 `/v1` 改为 `/v2`
- [ ] 从 URL 中移除 `api_key`,改用 `Authorization: Bearer` 请求头
- [ ] 列表请求改用 `limit` 与 `cursor`,删除 `page` 与 `per_page`
- [ ] 请求体中的 `qty` 改为 `quantity`
- [ ] 读取响应时改用 `quantity`
- [ ] 错误处理改为读取 `error.code` 与 `error.message`
- [ ] 为 429 响应增加退避重试逻辑
- [ ] 在测试环境跑一遍完整业务流程

测试一节要告诉开发者验证什么:用真实数据跑一遍列表、查询、增减库存三条主流程,确认分页能翻到最后一页、错误分支能正确进入、限流时不会崩溃。回滚一节说明在迁移期间如何退回 v1——只要 v1 还在服务期内,把基础 URL 和鉴权方式改回去即可,这也是建议分阶段迁移、而不是一次性全量切换的原因。

一个完整示例

把上面的步骤串起来,假设你要为一个「订单查询 API」从 v1 迁移到 v2 写指南,完整流程如下。

第一步,列变更。并排打开两份参考文档,逐节比对,得到清单:基础 URL 变化、鉴权方式从查询参数改为请求头、列表端点分页参数替换、响应字段 total 改名为 total_count、错误结构改为对象、新增 429。六项里五项是破坏性变更,一项按破坏性处理。

第二步,搭骨架。按「摘要 → 时间线 → 破坏性变更(逐项)→ 新特性 → 迁移清单 → 测试 → 回滚」组织,摘要里写明影响范围和截止日期,时间线表格列出「现在」与「停止服务」两个节点。

第三步,逐项写。每项统一四段式。以字段改名为例:

### 字段改名:total 改为 total_count

**变了什么:** 列表响应中的 `total` 改名为 `total_count`,数值含义不变。

**修改前(v1):**

```javascript
const data = await res.json();
console.log(`共 ${data.total} 条`);
```

**修改后(v2):**

```javascript
const data = await res.json();
console.log(`共 ${data.total_count} 条`);
```

**你需要做什么:** 所有读取 `total` 的位置改为读取 `total_count`,
包括日志、分页计算和前端展示。

第四步,收尾。把六项变更对应的动作压进迁移清单,补上测试要点(列表翻页、错误分支、限流重试)和回滚说明(服务期内改回 v1 的 URL 与鉴权方式)。

完成后通读一遍,用两个问题自检:一个只读了摘要的开发者,是否知道这件事与自己有关、截止日期是哪天?一个照着指南改代码的开发者,是否能在不回头翻参考文档的情况下完成每一项修改?两个答案都是「是」,这份指南就可以交付了。

注意事项

  • 不要只依赖参考文档。文档可能滞后于实际实现,变更日志和合并请求里常有文档没写的变化,最好找负责新版本的工程师确认清单。
  • 拿不准就按破坏性处理。新增响应字段、新增错误状态码这类改动,对大多数调用方无害,但对严格校验字段或只处理旧状态码的代码可能致命。漏写的代价远大于多写一节。
  • 同一处改名可能对应多条记录。请求侧和响应侧的字段改名要分开写,因为开发者修改的是代码的不同位置。
  • 截止日期必须显眼。放在摘要第一段并加粗;时间线用表格列出关键节点,避免读者在长文中翻找。
  • 「为什么改」要克制。只在原因能帮助开发者理解或下决心时写,一两句话即可,不要写成设计文档。
  • 版本号、截止日期、配额与限流阈值等信息会随时间变化,写作时以官方当前公布的信息为准,并在发布前复核一遍。