废弃的 API 还能跑,这正是陷阱
不停单把客户从 v1 迁到 v2,要靠适配层、并行运行和对写入逻辑的仔细核查,否则错误只会变成脏数据。
要点速览
- 过了废弃日期,v1 可能仍能用,但不再有人支持,不要把这个日期当成安全的截止线。
- 所有调用都走同一个适配层,让 v1 和 v2 并行运行,再用开关逐步切流。
- 最容易出问题的是写入逻辑(“读取-修改-写回”改为 PATCH)和错误格式,而不是 URL。
设想客户那边一个周一的早上。运营负责人转来一封软件供应商的邮件: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”比罗列一堆技术更有说服力,如果还能接着讲出你发现的那些错误路径问题,效果更好。
废弃通知邮件还会再来,来自这家供应商或别家。如果适配层和响应头日志已经就位,下次只需改一个文件,客户甚至察觉不到发生过什么。
这篇文章对你有帮助吗?
感谢你的反馈!