@Deprecated 是轻量但关键的沟通机制，需明确标注过时原因及替代方案、启用编译警告与IDE提示、分阶段迁移、配套文档与团队流程保障。
@Deprecated 不只是加个标签那么简单——它是一次轻量但关键的沟通，目的是让团队在不中断开发的前提下，逐步迁移到更优实现。用得好，能减少误用、降低维护成本；用得随意，反而会引发困惑或被直接忽略。
明确标注过时原因和替代方案
仅写 @Deprecated 没有说明，等于只按了警报却不告诉哪里着火。Javadoc 中必须清晰写出：为什么过时（如“线程不安全”“性能瓶颈明显”“API 设计违反单一职责”），以及推荐替代项（如“请改用 newServiceV2()” 或 “参考 MigrationGuide.md 第3节”）。
示例：
/**
* @Deprecated 已被 {@link UserServiceV2#findUserById(Long)} 取代。
* 原方法使用同步数据库查询，QPS 超过 50 后响应延迟显著上升；
* 新接口默认走缓存 + 异步刷新，吞吐提升 3 倍以上。
*/
@Deprecated
public User findUser(Long id) { ... }
配合编译警告与 IDE 友好提示
确保项目启用 -Xlint:deprecation（Maven 中配置 maven-compiler-plugin 的 compilerArgs），让构建时显式报出所有过时调用。同时，在 IDE（如 IntelliJ）中开启 “Show deprecated API usage” 提示，鼠标悬停即见迁移指引。
进阶建议：
- 对强耦合的旧类，可添加
@Deprecated(forRemoval = true)（Java 9+），表明下一版本将彻底删除 - 在 CI 流水线中增加检查：若新增代码引用了带
forRemoval = true的 API，直接失败并提示 PR 修改
提供渐进式迁移路径，而非一刀切
团队升级不是发布一个公告就结束。建议分三步走：
- 灰度阶段：新功能强制使用新 API；旧模块允许保留，但每次构建输出“仍有 X 处调用已标记为 forRemoval 的方法”统计
- 引导阶段：在日志中对旧方法调用打 warn 级别日志，附带简短迁移提示（如“[DEPRECATION] UserService.findUser() → 请切换至 UserServiceV2”）
- 清理阶段：下一个小版本移除旧实现，并同步更新文档、示例代码和内部培训材料
配套文档与团队共识不可少
在团队 Wiki 或内部技术规范中单列一页《过时代码管理流程》，明确：
- 谁有权标记
@Deprecated（建议需经模块 owner + 架构组双确认） - 标记后 7 天内必须同步提交迁移指南 PR，并关联到对应 issue
- 每季度扫描一次
@Deprecated使用率，对长期未降为 0 的条目组织专项复盘
把技术决策变成可追踪、可衡量、有节奏的协作动作，而不是靠人盯人提醒。
