用好@deprecated和@since的核心是明确演进路径：java 9起支持since（须语义化如"2.5.0"）和forremoval，配合javadoc@deprecated块说明废弃原因、替代方案及下线计划，并通过ci/cd、changelog、静态扫描等配套机制闭环治理。
用好 @Deprecated 和 @since，核心不是“标过时”，而是帮团队看清“从哪来、往哪去”。Java 9 起，@Deprecated 支持 since 和 forRemoval 两个属性，配合 Javadoc 中的 @deprecated 块，就能构成一条清晰的演进线索。
版本信息必须用语义化格式写进 since
写 @Deprecated(since = "2.5.0")，而不是 "v2.5" 或 "2.5"。原因很实际：
- 语义化版本（SemVer）是行业通用语言，能直接对应到 Maven 坐标、Git Tag 和发布日志
- CI/CD 工具（如 Dependabot、Renovate）可自动识别并触发升级提醒
- Gradle 构建中若
sourceCompatibilitysince 属性会被静默忽略——务必确认 Java 版本 ≥ 9
废弃说明要讲清“为什么废”和“换什么”
Javadoc 的 @deprecated 注释不是可选项，它是开发者看到的第一手迁移指南。光写“已废弃”没用，得给出上下文：
- 说明根本原因：是线程不安全？性能瓶颈？设计缺陷？还是协议变更？
- 明确指向替代项：用
{@link NewClass#method()}或{@code NewUtil.doX()}格式，IDE 可跳转、文档可渲染 - 必要时加简短示例：
@deprecated Use {@link #parse(Reader, ParseOptions)} with {@code ParseOptions.strict(true)}
区分“已弃用”和“即将删除”
forRemoval = true 是一个强信号，代表这个 API 进入淘汰倒计时：
- 它不是预测，而是承诺：下一个主版本（如 3.0）大概率移除
- 建议同步在文档中标注下线窗口，比如“计划于 v3.0 移除，请于 2026 年 Q3 前完成迁移”
- 搭配编译警告升级策略：在 CI 中启用
-Werror -Xlint:deprecation，让forRemoval相关调用直接失败，倒逼清理
配套动作不能只靠注解
单靠注解无法闭环。需建立轻量但有效的协同机制：
- 在 CHANGELOG.md 中为每个
@Deprecated条目单列条目，注明版本、原因、替代方案链接 - 内部 SDK 发布时，自动生成「待迁移清单」报告，按模块/负责人分发
- 对
forRemoval = true的 API，上线前做静态扫描（如 SpotBugs + 自定义规则），拦截新代码误用
