@Deprecated 可标注类、接口、方法、字段、构造器和枚举常量，常见于功能替代、API演进等过渡场景；不推荐用于局部变量、方法参数、包声明和注解类型。
@Deprecated 可以标注在几乎所有程序元素上，但不是所有位置都适合或有必要标记。关键在于：是否真有“过渡期需求”，以及是否对调用方构成实际维护风险。
哪些位置支持 @Deprecated（且常见）
Java 允许在以下位置使用 @Deprecated，且在真实项目中均有合理场景：
-
类/接口：整个功能模块被新设计替代，如
@Deprecated public class XmlParser（改用JsonParser） - 方法：最常用，比如线程不安全的旧工具方法、参数设计过时的 API
-
字段（含常量）：命名不规范的公共字段、语义模糊的静态常量（如
@Deprecated public static final int MAX_RETRY = 3;→ 替换为DEFAULT_RETRY_LIMIT） - 构造器：当对象创建逻辑已收敛为工厂方法或构建器模式时，可废弃带多参数的公有构造器
-
枚举常量：业务状态值变更，如
@Deprecated PENDING→ 改用AWAITING_APPROVAL
字段标注要注意什么
字段被 @Deprecated 后，IDE 会对其声明和所有直接赋值/读取处标删除线，但不会警告反射访问或序列化场景。因此需额外注意：
- 若字段是
public static final常量，必须同步更新所有引用它的字面量或硬编码值 - 若字段参与序列化（如
Serializable类），需确保反序列化兼容性，否则客户端升级后可能失败 - 建议搭配 Javadoc @deprecated 说明迁移方式，例如：
/** @deprecated 使用 {@link #getTimeoutMillis()} 替代，单位统一为毫秒 */@Deprecated public long timeout;
构造器标注的典型场景与写法
构造器弃用通常出现在 API 设计演进中，核心目标是引导用户转向更安全、更明确的初始化方式：
- 参数易混淆：如
new User(String, String, int)不清楚各参数含义 → 改为User.builder().name(...).email(...).build() - 违反不可变原则：公有构造器暴露内部状态可变风险 → 标记为 @Deprecated，只保留私有构造 + 静态工厂
- 需强制校验：旧构造器不校验参数，新工厂方法可抛出
IllegalArgumentException
写法示例：
@Deprecated(since = "3.2.0", forRemoval = true)
public User(String name, String email) {
this.name = name;
this.email = email;
}
<p>public static User of(String name, String email) {
Objects.requireNonNull(name);
return new User(name, email);
}不推荐标注的位置
以下位置虽语法合法，但实践中应避免滥用 @Deprecated：
- 局部变量：生命周期短，无跨文件影响，加注解无实际价值
- 方法参数：Java 不支持对单个形参加 @Deprecated；如需提示，应在方法级标注并说明哪个参数已淘汰
- 包声明：JDK 本身未定义该用法，多数 IDE 和构建工具不识别，属于无效标注
- 注解类型自身：极少需要，除非你正在废弃一套自定义注解体系
