API废弃是API生命周期管理的最后一环。很多团队的API库中充斥着废弃接口，占用维护精力且混淆新开发者。规范的废弃策略能帮助API平滑下线，减少对使用方的冲击。本文分享API废弃的策略和实战经验。
废弃声明周期
API废弃不是一个动作而是一个过程。生命周期：标记废弃（API文档中标注@deprecated）、继续维护期（功能正常但不再新增特性）、枯萎期（响应中添加废弃头提醒）、最终下线（返回410 Gone）。每个阶段的时长根据API的重要程度和使用频率决定。核心API的废弃周期至少12个月，非核心API至少6个月。
废弃通知机制
废弃通知要让每个API使用者知晓。文档标注：在API文档中明确标注废弃状态和替代方案。响应头添加Deprecation头和Sunset头：Deprecation: true 表示已废弃，Sunset: 日期 表示下线日期。调用日志中记录使用废弃API的客户端信息，便于通知。主动发送邮件或站内信通知API的使用方，告知废弃计划和迁移指南。
客户端迁移推动
API废弃后需要推动客户端迁移。迁移指南：提供新旧API的对照表和代码示例。迁移工具：提供自动化迁移脚本，降低迁移成本。迁移窗口期：设置合理的过渡期，让客户端有充足时间改造。迁移状态追踪：了解哪些客户端尚未迁移，定向跟进。废弃API的访问量监控：持续关注废弃接口的使用情况，推动高频使用者尽快迁移。
最终下线流程
确认所有客户端已迁移后执行最终下线。下线前复查：检查所有依赖方是否已迁移，确认没有遗漏。下线操作：关闭服务端路由或返回410 Gone。观察期：下线后观察一段时间，如有客户端报错及时恢复。归档文档：API文档移入历史版本区，标注已下线。回顾总结：分析API废弃的经验教训，优化新API的设计避免过早废弃。