开放接口从 v1 升到 v2 后，装机量还有 3 万的老客户端全部报 404 invalid_api，客服一天接了 200 通电话。第一次遇到会往复杂处想，其实漏掉的多是个小前提。
curl -i https://api.example.com/v1/order curl -i https://api.example.com/v2/order
新版本只保留 /v2/ 路径，/v1/ 直接下线，老客户端写死的地址找不到。响应体里也没有升级提示，客户端只能弹一个通用错误。这一点先确认清楚，后面就不用反复试。
碰到「接口版本升级兼容」这类问题，我习惯先把当前配置原样备份一份，改坏了立刻换回来，不用现场推。临时改动用注释写上日期和原因，过两周自己都记不清为什么这么写。
动手前把原文件复制一份带时间戳，出问题立刻换回去，比现场分析快得多。一次只改一处，改完立刻验证，几个改动叠在一起，出问题就说不清是谁导致的。
具体做法是，把 v1 路径恢复成转发层 内部映射到 v2 实现；响应头加 Deprecation 和升级文档链接；统计 v1 调用来源 按客户端版本给迁移期；迁移期结束后再摘掉转发。
改完照着核一遍，老客户端请求 v1 返回 200 并带上 Deprecation 头 404 数量归零。