@Deprecated是过渡信号而非下线指令，需分四阶段推进：标记废弃、灰度观察期（2～4周）、强制拦截期（可选）、物理移除。

在生产环境中，@Deprecated不是下线指令，而是过渡信号——它不阻断运行，但必须配合明确的下线节奏和可观测手段，否则容易变成“挂着的废弃接口”，长期占用维护成本、埋藏兼容风险。

明确区分“标记废弃”和“实际下线”两个阶段

很多团队误把加@Deprecated当作下线完成。实际上这只是第一步，后续必须分阶段推进：

• 标记废弃（Deprecated）：在接口/类/方法上添加@Deprecated，并配套@deprecated Javadoc，写明原因和替代方案（如“请改用UserV2Service.queryById(Long)”）；
• 灰度观察期：通过日志、链路追踪或网关埋点，统计该接口在生产环境的真实调用量、调用方IP/AppID、错误率等；建议设置至少2～4周观察窗口；
• 强制拦截期（可选）：对仍在调用的客户端返回410 Gone或自定义错误码（如ERR_DEPRECATED_API），附带迁移指引文案；此阶段需提前通知关键调用方；
• 物理移除：确认调用量归零或低于阈值（如

让@Deprecated真正被看见、被响应

仅加注解远远不够。IDE警告只作用于开发阶段，生产环境没人看编译日志。要让它生效，得联动基础设施：

• 在Spring Boot中，可通过@ControllerAdvice统一拦截被@Deprecated标记的@RequestMapping方法，自动记录WARN日志并打标deprecated=true到监控指标；
• API网关层配置规则：识别路径或Header中含X-Deprecated-Warning的请求，自动上报至告警平台，并关联调用方身份；
• CI流程中加入检查：使用javac -Xlint:deprecation + -Werror（测试/预发环境启用），阻止新代码继续引用已废弃接口；
• OpenAPI文档生成时，自动将@Deprecated映射为deprecated: true字段，并在Swagger UI中显示“Deprecated”徽章和跳转链接。

配套版本管理与生命周期看板

单个接口的废弃必须放在整体API演进框架里管理，否则易碎片化：

• 所有对外接口按路径前缀划分版本（如/api/v1/users、/api/v2/users），v1进入Deprecated状态后，禁止新增字段或行为变更；
• 维护一份内部API生命周期表，包含字段：接口路径、废弃日期、下线截止日、当前调用量（7d avg）、主要调用方、替代路径；
• 每月同步该表给前端、APP、第三方合作方，并在企业微信/钉钉群置顶公告；关键接口下线前7天发送正式下线提醒邮件。

避免常见陷阱

这些做法看似合理，实则会削弱@Deprecated的效力：

• 只在实现类加@Deprecated，而接口本身未标记——调用方仍可通过接口多态调用，失去提示意义；
• 废弃接口返回空结果或静默忽略请求——掩盖问题，导致调用方误以为“还能用”，拖长下线周期；
• 未同步更新Mock服务或SDK——下游测试仍能跑通，上线后才暴露异常；
• 把@Deprecated当“技术债备忘录”长期挂着，三年不清理——团队默认它就是正常接口的一部分。