你如何对 API 进行版本管理并在服务之间保持向后兼容性？

Question

Accepted Answer

由于服务独立部署，你无法假设调用方会同步升级。**API 版本管理**加上**向后兼容性**使生产方能够演进而不破坏现有消费方。

## 版本管理策略

| 策略 | 示例 |
|---|---|
| URI 路径 | `GET /v2/orders/42` |
| Header | `Accept: application/vnd.api.v2+json` |
| Schema 演进 | 添加字段，永远不删除/重命名 |

## 倾向于加法式（非破坏性）变更

```text
NON-BREAKING (safe):
  ✓ add a new optional field
  ✓ add a new endpoint
  ✓ add a new enum value (if clients tolerate unknowns)

BREAKING (needs a new version):
  ✗ remove or rename a field
  ✗ change a type or make a field required
  ✗ change semantics of an existing field
```

## Protobuf 对此很友好

```proto
message Order {
  string id = 1;
  double total = 2;
  string currency = 3;  // NEW field 3 — old clients ignore it safely
}
```

字段编号而非字段名定义了 wire 格式，因此添加字段是向后兼容的。

## 生命周期

```text
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
```

## 陷阱

当真实流量仍在使用某个版本时，永远不要删除它。在下线前跟踪使用情况。

## 为什么这很重要

独立可部署性仅在生产方能够在不协调每个消费方发布的情况下交付变更时才能工作。

为加法式变更而设计并在迁移期间支持旧版本，这才是保护这种独立性而不是强制脆弱的全量升级的关键。

URI 路径	`GET /v2/orders/42`
Header	`Accept: application/vnd.api.v2+json`
Schema 演进	添加字段，永远不删除/重命名