@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 才可物理移除。

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！