从 `@Deprecated` 规范到流量硬下线：谈谈后端 API 废弃计划与调用方清单治理实践

最近在梳理老项目（顺带在做 Spring Boot 2.7 升 3.x 相关的技术债清理），发现最头疼的永远不是代码重构，而是接口废弃（API Deprecation）治理。

平时在 Controller 里随手打了 @Deprecated，Springdoc (OpenAPI 3) 生成的文档上也确实有了划线标记，但实际情况大家都懂：调用方几乎视而不见，老接口永远处于“不敢删、不敢改、监控里又偶尔跳出一两个请求”的薛定谔状态。

我们团队目前尝试落地的做法比较偏工程防御：

1. 网关层做规范通知：在 Spring Cloud Gateway 这一层针对标记废弃的路由统一注入 Deprecation 和 Sunset 响应头（参考 RFC 8594），明确给出下线日期与替代 API 文档地址。
2. 流量归因与日志拉网：通过 Micrometer 埋点或网关 Access Log，把带有特定 Client-Id / App-Id 的老接口请求聚合成报表，生成真实的“调用方下线清单”，由架构组定期催促业务方改造。

但踩过的坑依然不少：

• 很多历史老系统调用没传独立凭证（直接混用公共 Token），根本查不到责任人。
• 外部对接方往往不看 HTTP Header，直到我们在预发环境把接口改成返回 410 Gone 时，才会有业务方跑来提工单。

想请教一下大家团队是怎么维护废弃计划的？

• 你们有在网关层做“灰度下线”吗？（比如下线前两周开始对废弃接口做间歇性限流、注入 500ms 延迟逼迫调用方排查，还是直接按 SLA 硬切 410？）
• 调用方清单的追踪是完全依赖链路追踪（SkyWalking / OpenTelemetry），还是有一套专用的 API 资产治理平台来跟进？