让警告可见
弃用响应头把迁移截止日期放进响应本身。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,而不是没有标记的成功响应。