Java @Deprecated Annotation(注解)

在本部分的快速指南中,我们将会查看 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 我们可以为其设置一些其他的属性以及这些属性的默认值。