@Deprecated 仅是编译期提示，非运行时阻断；企业级下线需四步协同：标注+JavaDoc、CI拦截、运行时告警、自动化扫描，并配套版本契约与文档同步。
理解 @Deprecated 的真实作用边界
@Deprecated 本身只是编译期提示，不阻断调用、不触发运行时逻辑、也不影响字节码执行。它在企业级脚手架中真正的价值，是作为「信号灯」而非「闸门」——告诉开发者“这个 API 已进入淘汰流程”，但下线必须靠配套机制协同推进。
四步渐进式下线策略（非简单打标）
在 Spring Boot + Maven 构建的企业级脚手架中，推荐按节奏分阶段执行：
-
第一阶段：标注 + JavaDoc 强提示
在方法上加
@Deprecated，同时在 JavaDoc 中明确写清替代方案、下线时间窗口（如“计划于 v3.2.0 移除”）、迁移示例代码。避免只写“已废弃”这种无效信息。 -
第二阶段：CI 层拦截新增使用
在 Maven 的
maven-compiler-plugin中启用compilerArgs = ["-Xlint:deprecation"]，再配合 CI 脚本（如 GitHub Actions 或 Jenkins）将-Werror加入编译参数，使新引入的@Deprecated调用直接导致构建失败。 -
第三阶段：运行时埋点告警
利用 Spring AOP 或字节码增强（如 ByteBuddy），对被
@Deprecated标记的方法做环绕通知，在日志中输出调用栈 + “此 API 将于 X 版本下线”，并上报至监控系统（如 Prometheus + Grafana）。生产环境可配置开关控制是否告警。 -
第四阶段：自动化扫描 + 迁移辅助
集成
revapi-maven-plugin或自研 AST 扫描工具，在每日构建中识别全量模块对已废弃 API 的依赖，并生成迁移报告；更进一步可结合 LSP（如 jdt.ls）在 IDE 中提供一键替换建议（如把UserService.findUserById()替换为UserQueryService.findById()）。
配套治理：版本契约与文档同步
仅靠注解无法完成平滑下线。需同步做到：
- 在脚手架的
CHANGELOG.md和内部 Wiki 中，为每个废弃项建立独立条目，包含影响范围、兼容周期、升级 check list； - 在脚手架父 POM 中通过
properties定义统一的废弃策略版本号（如deprecated-api-cycle=3.2），供各子模块读取并校验自身是否已清理； - 发布前强制触发
mvn verify -Pcheck-deprecation，该 profile 执行静态分析 + 接口契约校验（如 OpenAPI spec 中是否已移除该端点）。
特别注意：避免三个典型陷阱
不要只打标签就发版 —— 这会让下游团队误以为“还能用一阵子”，反而延迟响应；不要废弃整个类却遗漏其构造器或静态工厂方法 —— 它们同样需要单独标注；不要跨大版本直接删除 —— 如 v2.x 废弃的 API，至少要在 v3.x 全生命周期内保留，v4.x 才可物理移除。
