接口下线要有流程
接口废弃不是改一行路由，而是一段有公告、有监控、有分批关停的过渡期。规范做法是：先把接口标记为弃用并通过响应头告知调用方，同时给出替代接口与迁移指引；再用监控统计存量调用方与调用量，按批次推进迁移；最后在约定的日期关停。目标是让调用方有可执行的迁移路径，而不是在某个时间点突然收到 404。
基本信息
| 公告 | 文档标注弃用状态、替代方案、关停日期与迁移步骤 |
|---|---|
| 响应头 | Deprecation 与 Sunset 头，机器可读地传达弃用与关停时间 |
| 监控 | 按调用方与接口统计存量调用量，识别未迁移方 |
| 节奏 | 分批关停：先非活跃调用方，再处理遗留难点并单独跟进 |
典型使用场景
- 版本升级：v1 下线前完成调用方迁移到 v2
- 字段废弃：保留响应字段但标注弃用，给消费方留出改造期
- 内部服务收敛：合并重复接口，需要推动多个团队改造
- 对外开放平台：按合同与公告期执行下线，避免合规风险
- 安全整改：存在风险的老接口需要加速下线，同时提供替代方案
响应
响应
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.example.com/migrate-v2>; rel="sunset"关停前的检查项
| 检查项 | 判定标准 | 未通过时的动作 |
|---|---|---|
| 存量调用量 | 归零或仅剩已知豁免方 | 按调用方逐个联系并协助迁移 |
| 替代方案可用性 | 替代接口已覆盖同等能力且性能达标 | 先补齐能力再推进下线 |
| 文档与公告 | 迁移指引、关停日期已发布并被确认收到 | 补充公告并留出书面确认记录 |
| 回滚预案 | 关停后出现问题能快速恢复路由 | 保留开关与旧版本部署能力 |
| 监控告警 | 关停后的 404 能被区分并告警 | 把旧路径错误码纳入专项看板 |
使用要点
- 弃用期要按调用方迁移能力协商：对内可统一节奏，对外需按合同与公告期执行
- 公告要定向触达：文档发布之外，还要对已知调用方做一对一通知并留记录
- 监控要能按调用方维度拆解调用量，总量下降但个别调用方未动是常见盲点
- 关停用开关而不是删代码，保留快速恢复路由的能力
- 把废弃清单纳入常态化管理，避免弃用接口长期挂着无人跟进
弃用期要按调用方迁移能力协商：对内可统一节奏，对外需按合同与公告期执行，公告期长度要写进对外承诺而不是临时决定。
关停前务必确认监控能识别旧路径的错误：关停后调用方报错会先出现在对方系统，自身如果没有旧路径维度的告警，会错过最需要解释的时间窗口。