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