FDE Times 数据在招 FDE 职位 881▼8 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 55在招公司 185支持远程 25%美国薪资中位数 $201k招聘最多 Databricks 98
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

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

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

分享微博

要点速览

  • 过了废弃日期,v1 可能仍能用,但不再有人支持,不要把这个日期当成安全的截止线。
  • 所有调用都走同一个适配层,让 v1 和 v2 并行运行,再用开关逐步切流。
  • 最容易出问题的是写入逻辑(“读取-修改-写回”改为 PATCH)和错误格式,而不是 URL。
前后对比示意图。在 v1 中,更新订单状态需要三步:GET 整条记录、修改 status 字段、再用 PUT 覆盖整条记录。PUT 这一步以橙色高亮,因为两个进程同时写入时,后写入的会抹掉先写入的改动。在 v2 中只剩一次调用:只 PATCH status 这一个字段。
在 v2 中,v1 里读取、修改、覆盖整条记录的三步,被一次只发送待修改字段的 PATCH 调用取代。因此,凡是暗中依赖重写整条记录的代码都必须重新检查。来源:文中引用的 Chainguard v2 迁移指南。

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

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

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

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

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

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

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

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

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

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

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 会改变写入的方式,代码里凡是暗中依赖“重写整条记录”的地方,都要重新审查。

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

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 里就不存在了。结果是:临时性错误得不到重试,或者永久性错误被无限重试。系统不会崩溃,订单只是悄悄停在错误的状态里。

“查找替换”式迁移

  • 把 /v1/ 查找替换成 /v2/
  • 跑一遍正常路径测试
  • 一次部署 100% 切换
  • 等客户投诉才发现 bug

零停机迁移

  • 根据废弃响应头日志整理接口清单
  • 审查代码中所有写入数据的地方,尤其是整条记录覆盖
  • 重新测试每个错误码和重试逻辑
  • 在开关控制下逐步切流,并保留回退到 v1 的通道

在客户现场的执行顺序

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

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

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

常见错误

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

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

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

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

这篇文章对你有帮助吗?

4 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力一份 OpenAPI 文件,上线前揪出 500 错误Schemathesis 依据客户的 schema 生成请求、排查服务端错误,但它发的是真实流量,只能对准预发布环境。