Java @Deprecated Annotation（注解）

在本部分的快速指南中，我们将会查看 Java 的 deprecated API 和如何在程序中使用 @Deprecated 注解。

@Deprecated Annotation（注解）

作为程序的进化和迭代，随着时间的推移，在项目中总会有些类，构造方法，字段，类型或者方法不建议人们继续继续使用。

为了避免程序向后兼容的问题，而导致程序或者 API 不能使用，我们将会对不再使用的元素使用 @Deprecate 注解来声明。

@Deprecated 主要目的是告诉其他的开发者标记的元素不要在程序中继续使用了。

同时我们还建议在 @Deprecated 注解后面添加一些说明的文本来解释如果希望程序或者 API 具有相同的功能应该使用何种其他的方法。

SRC

https://github.com/cwiki-us-demo/java-tutorials/blob/master/core-java-modules/core-java-annotations/src/main/java/com/ossez/annotations/ClassWithDeprecatedMethod.java

package com.ossez.annotations;
public class ClassWithDeprecatedMethod {
/**
* Calculate period between versions
* * @deprecated
* * This method is no longer acceptable to compute time between versions.
* * <p> Use {@link ClassWithDeprecatedMethod#updatedMethod()} instead.
*/
@Deprecated
public static void deprecatedMethod() {
}
/**
* Updated Method instead of deprecatedMethod.
*/
public static void updatedMethod() {
}
}

请注意，如果一个 Java 的元素被声明了，但是又在程序或者项目的其他地方被引用的话，编译器将会显示丢弃（deprecated）API 的警告。

在上面的示例代码中，如果 deprecatedMethod 被调用了，只有调用 deprecatedMethod 这个方法显示丢弃的警告。

同时请注意，通过使用 Javadoc @deprecate 标记，我们将会在 Java 文档中也被标记丢弃。

上面的代码，如果在 IDE 中查看文本，将会显示为如下：

Java 9 添加的可选属性

针对 Java 9 的 @Deprecated 注解，还添加了 since 和 forRemoval 属性。

since – 接受字符串的输入参数，用于定义我们丢弃的内容从哪个版本开始。默认为空字符串。

forRemoval – 使用布尔（boolean）类型，用于标记我们丢弃的内容是不是从下一个发行的版本就会被删除。默认为 false。

如下面的代码中对上面属性的定义。需要注意的是，这个功能最低的版本为 Java 9，如果你还在使用 Java 8 的话，是不能被支持的，将会出现编译错误。

/**
* Calculate period between versions
* * @deprecated
* * This method is no longer acceptable to compute time between versions.
* * <p> Use {@link ClassWithDeprecatedMethod#updatedMethod()} instead.
*/
@Deprecated(since = "4.5", forRemoval = true)
public static void deprecatedMethod() {
}

上面的内容表示的是 deprecatedMethod 方法是从版本 4.5 开始准备丢弃的，同时已经计划在下一个主要的发行版本中完全丢弃删除。

通过添加上面的内容，如果我们现在还在尝试使用这个方法的话，将会通知编译器给我们一个非常强烈的警告。

同时，当前的主流 IDE 工具也能够明显的显示上面强提示。例如在 IntelliJ 中，删除线将会使用一个红色的删除线来替代当前使用的黑色删除线。

结论

在这个快速文章中，我们看到了如何使用 @Deprecated 声明来标记不再使用的元素，以及针对 Java 9 我们可以为其设置一些其他的属性以及这些属性的默认值。

完整的代码，请参考 GitHub中的项目，可能项目中的源代码和文章中使用的代码有所不同，请以 GitHub 中的代码为主。

代码和内容的完整链接为：https://www.cwiki.us/display/JAVAZH/Java+@Deprecated+Annotation