在本部分的快速指南中，我们将会查看 Java 的 deprecated API 和如何在程序中使用 @Deprecated 注解。
@Deprecated Annotation（注解）
作为程序的进化和迭代，随着时间的推移，在项目中总会有些类，构造方法，字段，类型或者方法不建议人们继续继续使用。
为了避免程序向后兼容的问题，而导致程序或者 API 不能使用，我们将会对不再使用的元素使用 @Deprecate 注解来声明。
@Deprecated 主要目的是告诉其他的开发者标记的元素不要在程序中继续使用了。
同时我们还建议在 @Deprecated 注解后面添加一些说明的文本来解释如果希望程序或者 API 具有相同的功能应该使用何种其他的方法。
SRC
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/[email protected]+Annotation
Comments