← 中文资源

简体中文版本

为 API 添加弃用响应头

用 Deprecation、Sunset 和 Link 头公布弃用期限,持续测量真实调用方,并在日落日期且有证据后移除旧端点。

阅读英文原文

让警告可见

弃用响应头把迁移截止日期放进响应本身。Deprecation 表示端点已弃用,Sunset 给出移除日期,Link 指向替代版本。记录响应头的客户端能在移除前很久就暴露警告。

Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: </api/v2/resource>; rel="successor-version"

测量真实使用

响应头不能证明客户端已经迁移。按客户端和端点记录调用,并建立展示活跃调用方随时间变化的仪表盘。直接联系主要消费者。如果使用量没有归零,要么用新的日落日期延期,要么接受有记录的破坏性变更。

有证据地移除

只有在剩余调用方已知且已处理时,才在日落日期后下线端点。移除响应头、路由和兼容分支,并更新文档。无限期运行的弃用端点既是技术债,也是安全面。

验证响应

预期结果:旧路由的每个响应都包含 Deprecation、Sunset 和指向后继版本的 Link,迁移仪表盘记录客户端 id 和路由。用 curl -sI 对已部署路由确认,并检查调用出现在使用日志中。下线后,同一请求应返回 404 或 410,而不是没有标记的成功响应。