@Deprecated是过渡信号而非下线指令，需分四阶段推进：标记废弃、灰度观察期（2～4周）、强制拦截期（可选）、物理移除。
在生产环境中，@Deprecated不是下线指令，而是过渡信号——它不阻断运行，但必须配合明确的下线节奏和可观测手段，否则容易变成“挂着的废弃接口”，长期占用维护成本、埋藏兼容风险。
明确区分“标记废弃”和“实际下线”两个阶段
很多团队误把加@Deprecated当作下线完成。实际上这只是第一步，后续必须分阶段推进：
-
标记废弃（Deprecated）：在接口/类/方法上添加
@Deprecated，并配套@deprecatedJavadoc，写明原因和替代方案（如“请改用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当“技术债备忘录”长期挂着，三年不清理——团队默认它就是正常接口的一部分。
