Java @Deprecated 注解详解

1. 概述

在本篇中，我们将快速了解一下 Java 中如何标记过时的 API，并重点介绍 @Deprecated 注解的使用方式。

2. @Deprecated 注解

随着项目的演进，API 也会不断变化。在这一过程中，一些构造方法、字段、类或方法可能会变得不再推荐使用。

为了避免破坏向后兼容性，我们可以使用 @Deprecated 注解来标记这些元素。

✅ @Deprecated 的作用是告诉其他开发者：这个元素已经不推荐使用了。

通常还会配合 Javadoc 来说明为什么不推荐使用，以及推荐使用哪个替代方案：

public class Worker {
    /**
     * 计算版本之间的周期
     * @deprecated
     * 此方法已不再适用于版本间时间计算。
     * <p> 请改用 {@link Utils#calculatePeriod(Machine)}。
     *
     * @param machine 实例
     * @return 计算结果
     */
    @Deprecated
    public int calculate(Machine machine) {
        return machine.exportVersions().size() * 10;
    }
}

⚠️ 注意：只有当被标记为 @Deprecated 的元素在代码中被调用时，编译器才会发出警告。

此外，我们还可以在 Javadoc 中使用 @deprecated 标签来进一步说明该元素的弃用状态。

3. Java 9 新增的可选属性

从 Java 9 开始，@Deprecated 注解新增了两个可选属性：since 和 forRemoval。

• since 属性用于指定该元素从哪个版本开始被标记为弃用，默认值是空字符串。
• forRemoval 是一个布尔值，表示该元素是否会在未来的版本中被移除，默认值为 false。

示例如下：

public class Worker {
    /**
     * 计算版本之间的周期
     * @deprecated
     * 此方法已不再适用于版本间时间计算。
     * <p> 请改用 {@link Utils#calculatePeriod(Machine)}。
     *
     * @param machine 实例
     * @return 计算结果
     */
    @Deprecated(since = "4.5", forRemoval = true)
    public int calculate(Machine machine) {
        return machine.exportVersions().size() * 10;
    }
}

这段代码的意思是：calculate 方法从版本 4.5 开始被弃用，并且计划在下一个主版本中被移除。

💡 使用这两个属性的好处是：

• 编译器会给出更强烈的警告信息。
• IDE（如 IntelliJ IDEA）也能识别 forRemoval = true 的方法，并以红色删除线高亮显示，而不是普通的黑色删除线。
  参考示例：IntelliJ 中的增强弃用提示

4. 总结

在这篇文章中，我们介绍了 @Deprecated 注解的基本用法及其在 Java 9 中新增的属性。

通过合理使用这个注解，可以在不影响现有代码的前提下，优雅地引导开发者迁移到新的 API。

📌 示例代码完整版可在 GitHub 获取：https://github.com/eugenp/tutorials/tree/master/core-java-modules/core-java-annotations