接口升级后老客户端用不了，旧接口要不要保留？

服务端接口升级后，老客户端用不了，多数情况不是用户不愿意更新，而是服务端把旧接口的请求契约改了，比如新增必填无默认值字段、改变返回类型、调整错误码语义。2026年项目交付的常见做法是：正式对外接口先做兼容期，新旧版本并行，再按旧版本调用占比决定何时下线。经验区间通常是：至少保留1个客户端发版周期，移动端常见1～2个月；或者等旧版本调用占比连续7天低于5%后，再安排删除。本文只讨论服务端如何对待旧接口，不展开灰度流量切换。

先查契约，不要急着催用户升级

客户端与服务端能走通，靠的不是代码漂亮，而是两边对报文格式、字段含义、取值范围的约定一致。升级时如果把一个非必填字段改成必填，或把返回字段从字符串改成数字，老客户端没能力提前感知，自然会被新逻辑拒绝。

排查步骤建议固定为两步：先在网关或应用日志里找到“版本号+请求路径+响应码”，再拿新旧接口定义做一次diff。重点检查必填项、返回值类型、枚举值、签名规则，常见不兼容几乎都藏在这四类里。

• 请求参数增加“必填且无默认值”的字段，老请求会直接报参数错误。
• 返回字段改名或删除，客户端解析时会收到空值或类型错。
• 错误码语义改变，客户端会走进原本不匹配的提示分支。
• 签名串字段顺序或参与集合变化，旧端加密逻辑会整体失败。

这里容易误判：只看应用监控里没有异常就认为服务端没问题。实际上，服务端看着正常，可能是老流量已经被转到了新逻辑，再由新契约拒绝了老请求。

先分清楚：哪些升级可以不留旧接口

不是每次改接口都必须保留旧版本。如果你能控制请求方版本，比如内部管理后台、同一个团队维护的服务调用、尚未发布的预发环境，都可以前后端一起改一起发，不必重复维护旧逻辑。

反之，面向应用市场审核的App、小程序、被第三方长期调用的接口，以及无法远程升级的IoT设备，建议把兼容期写进开发排期。能不能跳过兼容，核心就看一条：你是否能强制所有请求方升级到新版本。

旧接口留多久：按“观测-切换-下线”设触发器

旧接口保留多久不能只拍脑袋。按2026年项目交付习惯，应每个阶段设可验证的退出条件，不是“我们保留到某月就删”。

1. 观测：新接口上线后保留旧接口，记录老客户端调用次数、失败率和版本分布。观测期建议覆盖一个完整业务周期，常见经验区间是1～2周；若有月初、月末高峰，要跨过峰值。
2. 切换：新接口成功率稳定到可用水平（实践常见区间约为99%上下）且旧版本调用占比降到20%左右时，推动高版本客户端切到新接口。此时旧接口停止功能迭代，但不能删除。
3. 下线：旧版本调用占比连续7天低于5%，或距新版本发布超过1～2个月后，在低峰期删除；删除前在文档和响应头里提示旧版本将不可用。

如果旧版本占比一直不降，先找原因，例如用户被旧版本卡住无法升级，或者某个推送任务让用户停留在旧版。这时按日历硬删，容易把影响面放大。

URL版本和Header版本怎么选：边界不同

新旧接口要同时在线，服务端必须知道请求来自哪个版本。按常见经验：对外公开接口用URL路径版本，内部服务间用Header版本，改动范围很小时才考虑请求体里的version字段。

• URL路径版本（/api/v2/order）：路径清晰，在网关、日志、监控中直接可见；缺点是每个大版本都留一个路径。
• Header版本（X-Api-Version: 2）：不污染URL，适合内部服务；但日志和网关必须记录header，否则排障时难以定位版本。
• 请求体version字段：只能应对小差异，结构变化较大时会出现大量版本分支，一般不建议用于主版本。

不论选择哪种，缓存key、限流规则、监控报警都要带上版本标识。否则不同版本故障混在一起，你很难回答“该不该保留旧接口”。

保留旧接口的常见坑和一次现场经验

保留旧接口不意味着“controller复制一份就能跑”。实际交付中经常遇到：路由还在但代码已指向新逻辑，或只保留了HTTP层，数据库字段被新版本改掉，旧接口一执行就报错。常见问题大致有四种。

• 路由还在，但代码跑的是新逻辑，校验也换成了新规则，老客户端始终过不了。
• 数据库字段被删或改了默认值，旧接口执行时报字段不存在。
• 没有单独为旧接口配置超时和重试，新链路变慢时，旧链路被一起拖垮。
• 错误码没有按版本隔离，老客户端收不到它能识别的错误码。

验收动作建议固定为：上线前用老版本报文在测试环境跑通完整业务流，状态码、返回字段和错误提示都要与旧版一致。

一次实际交付经验：厂商已停止维护的旧终端无法改代码，但新接口必须上线。我们的做法是在网关层按来源IP或设备ID分流：旧设备继续走旧逻辑，新流量走新接口。这样兼容路由的经验区间为增加2～5人日开发联调，代价不小，但能避免上线当天老设备集体掉线。

适用与不适用边界

这套思路适合正式发布后无法强制升级请求方的场景，常见于App、桌面客户端、第三方开放接口和版本更新慢的IoT设备。如果你的调用方都是自己能控制的内部服务，同步升级更省事，没必要为“优雅”承担双倍维护成本。

旧接口也不是免费服务。每多保留一个版本，安全补丁、依赖升级、监控口径都会多一份。按2026年常见经验，对外同时保留的主版本建议不超过两个；旧版本过多时，更值得做数据面收敛，而不是让“兼容”长期掩盖升级失速。

本文方法适合新旧功能短期并存，不适合把兼容当作长期架构。需要跨年度维护的旧系统，建议用网关转发加独立配置隔离，而不是在主程序里堆版本分支。

常见问题

旧接口一般保留多久比较合适？

经验区间是：对外客户端至少保留1个发版周期，移动端常见1～2个月，或旧版本调用占比连续7天低于5%；内部系统可缩短到2周左右。

老客户端连不上，第一步先查什么？

先看网关或日志里的版本号、请求路径和响应码，再把新接口定义与老客户端依赖报文做diff，重点核必填项、返回字段、枚举值、签名规则。

版本标识用 /v2 好还是加请求头好？

对外公开接口建议用URL路径版本，内部服务间可用Header版本。两种方式都要在日志和监控中记录版本，否则难以定位故障。

老版本调用一直不降，能直接下掉旧接口吗？

不建议直接删。先查用户是否被旧版本卡住，或是否有强制阻断。确需继续保留，就设边界：不再新增功能，不频繁改动，并持续观察调用量。

发布新接口前，先回答“还有多少请求停留在旧契约上”。答案不清时别急着删旧代码。用“观测-切换-下线”的框架给每个阶段设阈值，数据到了再做决定。