升级旧接口，先确认调用方怎样使用它

常见变更怎么处理

按调用方与业务周期建立迁移名单

旧接口的使用者可能包括网页、小程序、APP、后台报表、批处理与合作方。代码搜索和近期访问日志都可能遗漏低频消费者。

结合接口密钥、客户端标识、调用日志与业务访谈建立名单，记录负责人、调用方法、升级方式和最长业务周期。无法识别的调用先归为待确认，不能因为没有人主动认领就视为可删。客户端发布不等于所有终端都升级，尤其 APP 和外部分发程序需要评估历史版本仍会存活多久。

• 列明每个调用方的接口、负责人和升级控制能力。
• 核对月末任务、离线终端和合作方的低频调用。
• 为未知调用保留调查方式和退役前处理条件。

兼容检查涵盖字段之外的业务约定

接口契约还包含默认值、空值、排序、时区、精度、错误码和重试含义。字段名称没变，并不代表客户端可以继续正确工作。

把现有请求与响应整理为契约样例，再与实际客户端解析方式核对。金额单位从元变分、日期从本地时间改为 UTC、列表默认排序改变，都可能不触发技术错误却改变业务结果。新增状态值也需确认旧客户端是否有兜底。兼容测试应优先覆盖真实旧版本，而不只测试团队当前开发分支。

调用方有时依赖文档未说明的行为，例如无数据时返回空数组或请求重复时返回相同对象。发现此类用法后先确认是否需要继续支持，再补入契约或迁移说明，不能仅以“文档没写”来判断它没有业务影响。

• 列出请求、响应、状态码和业务语义的完整差异。
• 保持原有默认行为，显式说明任何新增选项。
• 运行代表性旧客户端的解析与关键流程样例。

不兼容变化使用可识别的版本或适配路径

路径版本、请求头版本或其他约定都可采用，重点是路由确定、文档清楚、日志可区分，并且能独立统计各版本使用情况。

新旧接口共存时规定哪些能力只在新版出现，哪些旧行为继续保留。适配层负责兼容转换，避免把新版复杂规则硬塞回旧契约。主版本共存会带来维护成本，应有清晰结束条件；内部版本号修改不能替代服务路由，否则调用方看不出它实际获得哪种语义。

• 确定版本选择方式与缺省版本，记录路由规则。
• 为每个支持版本维护契约与兼容测试。
• 控制临时适配的功能范围和维护负责人。

弃用声明与停止服务日期分别传达

弃用提示说明旧接口应迁移，停止服务日期说明旧入口何时不再可用。可以结合标准响应头与人可读迁移文档，但不能假设所有客户端会自动识别。

RFC 9745 定义 Deprecation 响应头，RFC 8594 定义 Sunset 响应头；两者表达不同生命周期信息。实施时按标准核对格式，并提供新接口地址、变更说明和联系方。企业合作接口还应通过已约定的沟通渠道确认接收，响应头只是机器可读提示，不能替代迁移确认和业务协调。

• 公布迁移说明、替代接口、影响范围和支持方式。
• 分别记录弃用开始、预计退役与例外延期条件。
• 核对标准头格式及客户端能否实际读取提示。

迁移按试接、发布、观察和确认执行

调用方迁移应产生证据：新版联调样例、正式发布记录、旧版调用变化和负责人确认。仅在表格中写“已通知”不足以支持删除旧接口。

先让有控制能力的内部调用方完成迁移，检查流程与错误处理，再安排外部消费者。观察窗口应覆盖消费者最长运行周期，并排除监控漏采、标识缺失等原因。遗留客户端有明确业务价值时可安排受控兼容；没有必要继续支持的调用也需说明处理办法和停止后的错误行为。

为每个消费者保存新版覆盖的方法及剩余旧方法，避免只迁了登录却遗漏订单或报表。确认记录要指明客户端版本与日期，终端自动升级和人工安装的证明方式可能不同，按实际控制能力检查即可。

• 第一步：以真实调用样例完成新版联调与签收。
• 第二步：发布客户端并核对新旧版本调用分布。
• 第三步：完成周期性观察和遗留处理后确认退役。

正式退役包含文档、路由和后台引用清理

删除旧处理函数前，再检查文档、网关、任务、SDK 和测试中是否还存在旧引用。退役后的响应应符合约定，便于调用方定位。

本文适合需要维护多个消费者的企业 API。完全内部且所有调用方可同时控制的短生命周期接口，可以简化共存流程，但仍需要契约验证；由外部平台管理的 API 则要遵循平台支持窗口。零调用也不是无限可信的证据，应写明采样范围与识别方式。最终保留退役记录和迁移说明，便于解释历史错误。

• 核对网关、服务、任务与客户端库的旧引用。
• 明确退役后状态码、错误信息和支持入口。
• 记录版本结束、例外处理及历史文档存放位置。

需求讨论中的问题