# 废弃的 API 还能跑，这正是陷阱

> 不停单把客户从 v1 迁到 v2，要靠适配层、并行运行和对写入逻辑的仔细核查，否则错误只会变成脏数据。

原文: https://fdetimes.net/zh/guides/api-v1-to-v2-migration-without-downtime/

设想客户那边一个周一的早上。运营负责人转来一封软件供应商的邮件：API v1 将在某个日期停止支持，附带一份迁移指南的链接。邮件最后一行是客户写的：“这事你能处理吗？订单不能停。”

难点在于，没人会允许你停掉系统再切换。订单照常进来，同步照常运行，切换过程中的每个失误都会表现为错误的数据，而不是一个明确的异常。

有一套方法可以马上用起来：尽早发现，用适配层封装调用，两个版本并行运行，逐步切流，再专门复查那些最容易出问题的地方。

## 废弃日期不是安全的截止线

很多工程师的第一反应是把停用日期记进日历，再往前倒推几周。Webflow 针对 v1 发出的废弃通知说明了这种想法为什么危险：过了这个日期，v1 也许还能用，但不会再有维护、更新或支持。

**要点:** 废弃的 API 还能继续跑，这恰恰就是陷阱。

一个“还能用”却没人负责的 API，是最糟糕的一类风险。它随时可能出故障，出了问题也找不到人提工单。所以 Webflow 建议客户尽早开始迁移，避免集成中断。

理解供应商为什么这么做也有帮助。Stripe 自己就承认，向后兼容并不是免费的：每多一个版本，就多一份需要理解和维护的代码。不是每家供应商都愿意长期承担这笔成本，所以停用日期需要提前规划。

## 在邮件到来之前，让系统先提醒你

邮件会漏看，HTTP 响应头不会。RFC 9745 定义了 `Deprecation` 响应头，用来告诉调用方某个资源即将废弃或已经废弃。如果供应商同时发送 `Sunset` 响应头，它的时间戳不得早于 `Deprecation` 中的时间，这样废弃通知总是先于停用。

该 RFC 还允许通过关系类型为 `deprecation` 的 `Link` 响应头指向相关文档。并非每家供应商都会发送这些响应头，但把它们记进日志几乎没有成本。在客户的公共 HTTP 客户端里加上这段：

```python
import logging
import requests

log = logging.getLogger("vendor_api")
BASE = "https://api.vendor.example"

def call(method, path, **kw):
    resp = requests.request(method, BASE + path, timeout=10, **kw)
    if "Deprecation" in resp.headers or "Sunset" in resp.headers:
        log.warning(
            "已废弃接口 %s %s deprecation=%s sunset=%s link=%s",
            method, path,
            resp.headers.get("Deprecation"),
            resp.headers.get("Sunset"),
            resp.headers.get("Link"),
        )
    return resp
```

一周之后，日志就会给出一份清单：哪些接口确实在被调用，且已被标记为废弃。这份清单比任何人工盘点都可靠，因为它来自生产环境的真实流量。

## 示例：同步订单状态

假设客户有一个服务，负责把订单状态更新推送到供应商的系统。在 v1 里，唯一的做法是读取整条记录、改一个字段、再覆盖整条记录。v2 的文档写得很明确，和 Chainguard 的迁移指南类似：把“读取-修改-写回”的逻辑换成 PATCH 调用，只设置发生变化的字段。

这个细节比把 `/v1/` 改成 `/v2/` 重要得多，因为它涉及写入逻辑，也就是代码里所有发送数据以创建或修改记录的地方。

采用“读取-修改-写回”时，如果两个进程修改同一条记录，后写入的可能把先写入的改动抹掉。改用 PATCH 会改变写入的方式，代码里凡是暗中依赖“重写整条记录”的地方，都要重新审查。

所以第一步是让所有调用都经过同一个适配层，并且只在一处决定使用哪个版本：

```python
import zlib

V2_ROLLOUT_PERCENT = 5  # 逐步提高：5 -> 25 -> 50 -> 100

class VendorError(Exception):
    @classmethod
    def from_v2(cls, resp):
        # v2 的错误格式是新的：按 v2 文档解析错误码和错误信息
        return cls(f"{resp.status_code}: {resp.text}")

def use_v2(order_id: str) -> bool:
    return zlib.crc32(order_id.encode()) % 100 < V2_ROLLOUT_PERCENT

class OrderStatusClient:
    def update_status(self, order_id, status):
        if use_v2(order_id):
            return self._v2_patch(order_id, status)
        return self._v1_fetch_modify_write(order_id, status)

    def _v1_fetch_modify_write(self, order_id, status):
        item = call("GET", f"/v1/items/{order_id}").json()
        item["status"] = status
        return call("PUT", f"/v1/items/{order_id}", json=item)

    def _v2_patch(self, order_id, status):
        resp = call("PATCH", f"/v2/items/{order_id}", json={"status": status})
        if resp.status_code >= 400:
            raise VendorError.from_v2(resp)
        return resp
```

按 `order_id` 做哈希，能让每个订单始终落在同一个版本上，避免同一条记录混用两种写法。前提是供应商让两个版本并行运行。Chainguard 就是一例：v1 和 v2 同时运行，客户可以分批迁移，发布时也没有设定停用日期。

有些供应商允许更细粒度的控制。Stripe 会把每个账户固定在某个版本上，但允许通过 `Stripe-Version` 请求头按单个请求覆盖。

这意味着可以先在单个调用上试用新版本，再整体切换。如果你对接的 API 有类似机制，就在最初 5% 的阶段用上它。

## 真正的问题出在错误路径上

正常路径往往一次就跑通，所以很多团队过早宣布大功告成。Chainguard 的指南恰好提醒了这一点：v2 改变了错误格式和状态码，因此要重新测试错误处理路径，而不只是正常路径。

想想客户的重试代码。如果它靠匹配 v1 错误响应体里的某个字符串来决定是否重试，这个字符串在 v2 里就不存在了。结果是：临时性错误得不到重试，或者永久性错误被无限重试。系统不会崩溃，订单只是悄悄停在错误的状态里。

## 在客户现场的执行顺序

先记录一周响应头，拿到真实的接口清单。接着阅读迁移指南，标出每一处行为变更，尤其是写入方式和错误返回方式，因为这些需要重写，而不只是改路径。

然后搭建适配层，为两个分支都写好测试，把 v2 打开到 5%。在提高比例之前，观察错误率，并对比两组订单的数据。只有当 v2 以 100% 运行足够久、覆盖到每周和每月的定时任务之后，才删除 v1 的代码。

同时，给客户写一页简短说明：改了什么、当前切流比例是多少、出问题时如何回退到 v1。运营人员不需要看代码，但需要知道由谁、在什么时候拉下回滚开关。

## 常见错误

最常见的错误是把废弃日期当成停用日期，一直拖到最后一刻。其次是 API 调用散落在代码库各处，导致无法逐步切换，只能一次性全部改掉。第三是只测试正常路径，前文已经讲过。

一个较少被提及的错误是忘了那些边缘脚本：cron 任务、分析用的 notebook、某人两年前写的内部工具。它们不经过你的适配层，所以如果客户有共享的代理或网关，也要在那一层记录废弃响应头，以免遗漏。

在简历或面试中介绍这次迁移时，一句“按流量比例将集成 X 从 v1 零停机迁移到 v2，并把写入逻辑改写为 PATCH”比罗列一堆技术更有说服力，如果还能接着讲出你发现的那些错误路径问题，效果更好。

废弃通知邮件还会再来，来自这家供应商或别家。如果适配层和响应头日志已经就位，下次只需改一个文件，客户甚至察觉不到发生过什么。

**本周动手试试:**

- 在客户的 HTTP 客户端里加一行告警日志：只要响应带有 Deprecation 或 Sunset 响应头就记录下来，7 天后看看出现了哪些接口。
- 列出代码库中所有先读取整条记录再覆盖整条记录的地方，标出新 API 支持 PATCH 后需要修改的部分。
- 为你负责的某个集成写三个错误路径测试（400、404、429），分别在两个 API 版本上运行。

## 信源

- [RFC 9745: The Deprecation HTTP Response Header Field](https://www.rfc-editor.org/rfc/rfc9745.html)

- [APIs as infrastructure: future-proofing Stripe with versioning](https://stripe.com/blog/api-versioning)

- [Webflow v1 API Deprecation Notice](https://developers.webflow.com/data/v1.0.0/docs/webflow-v1-api-deprecation-notice)

- [Migrating from API v1 to API v2](https://www.chainguard.dev/docs/platform/api/api-v2-migration/index.md)
