主要的 API versioning 策略有哪些，如何 deprecate 一个版本？

Question

IT Interview Practice · Accepted Answer

Versioning 让你能在带有**破坏性变更（breaking changes）**的情况下演进一个 API，而不破坏现有的 client。有三种主流策略，外加一个 deprecation 流程。

## 三种策略

**1. URI versioning** —— 版本放在 path 中。
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
最简单、最可见；易于路由、缓存和在浏览器中测试。缺点：它在技术上违反了“URI 标识一个资源”（同一个 user 现在有两个 URL）。这是迄今为止最常见的选择（GitHub、Stripe 历史上如此）。

**2. Custom header versioning** —— 版本在一个 header 中传递。
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
保持 URL 干净，但在浏览器中不可见、也更难缓存。

**3. Media-type（内容协商）versioning** —— 版本在 `Accept` 中。
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
最“RESTful”（资源 URL 稳定，只有它的 representation 被版本化），但对使用者最不友好。

## 什么算是破坏性的

```text
BREAKING      → remove/rename a field, change a type, change auth, tighten validation
NON-BREAKING  → add a new optional field, add a new endpoint, add an enum value*
```
只有破坏性变更才需要新版本；把非破坏性变更加进当前版本。

## Deprecation 流程

1. 在文档和 changelog 中**公告**并附上日期。
2. 用 header 在**运行时发出信号**，让 client 能以编程方式注意到：
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. **监控**旧版本的用量并联系剩下的 caller。
4. 只在用量接近于零后才**下线（sunset）**。

## 为什么这很重要

面试官问这个，是想看你能否在生产环境中扩展一个 API 而不破坏依赖它的 client——这是一个真实的运营问题，而非理论问题。最强的回答会做两个区分：其一，**大多数变更是非破坏性的**，根本不应触发版本升级（增量变更进入当前版本），把 versioning 留给真正的破坏性变更；其二，*策略*不如*流程*重要——一个清晰的 deprecation 时间表，配上 `Deprecation`/`Sunset` header 和用量监控，才是真正保护使用者的东西。URI versioning 在实践中胜出，因为它可见且有工具支持，但知道各种取舍（header 和 media-type 保持 URL 稳定且更 RESTful，代价是可发现性）表明你理解设计空间，而不只是机械照搬 `/v1/`。

三种策略

什么算是破坏性的

Deprecation 流程

为什么这很重要

相关问题