Java @Deprecated 注释

@Deprecated 注解是在 Java 5 版本中引入的。一个被标注为 @Deprecated 的程序元素意味着不应该使用它，原因可能包括：

使用可能导致错误。
在未来的版本中可能会不兼容。
可能在未来的版本中移除。
有更好更高效的替代方案已经取代它。

编译器会在使用已废弃的元素时生成警告。在 Java 9 中，对 @Deprecated 注解做了两项新的增强。

Java 9 对 @Deprecated 注解的增强

1. forRemoval 属性

指示被注解的元素是否会在未来版本中移除。默认值是 false。

2. since 属性

返回被注解的元素是在哪个版本中被标记为废弃的。默认值为空字符串。

Deprecated with since

下面是一个在 Java 9 中 Boolean 类的 Javadoc 示例，展示了如何在 @Deprecated 注解中使用 since 属性。

Boolean 类

Boolean 类 Javadoc 示例

/**
 * Converts the specified string to a boolean value.
 * This method is deprecated since it does not handle
 * case sensitivity properly.
 *
 * @param s the string to convert
 * @return the boolean value represented by the string
 * @deprecated (since Java 9) Use {@link #parseBoolean(String)} instead.
 */
@Deprecated(since="9")
public static boolean booleanValueOf(String s) { ... }

Deprecated with forRemoval

下面是一个在 Java 9 中 System 类的 Javadoc 示例，展示了如何在 @Deprecated 注解中使用 forRemoval 属性。

System 类

System 类 Javadoc 示例

/**
 * Sets the specified property for the system.
 * This method is deprecated as it poses a security risk.
 *
 * @param propName the name of the property to set
 * @param propValue the value of the property
 * @deprecated (forRemoval=true) This method will be removed in a future release.
 */
@Deprecated(forRemoval=true)
public static void setProperty(String propName, String propValue) { ... }