Java @Deprecated 註解作用與傳遞性深度解析

前言

@Deprecated 是 Java 標準註解，用於標記不再推薦使用的 API。但許多開發者誤以為它具備「繼承傳遞性」——即父類標註後，子類自動生效。本文實測驗證其實際行為，並說明 IDE 與編譯器的差異。

一、@Deprecated 基本作用

• 標記類、方法、欄位、建構子等程式元素「過時」
• 編譯器在使用處發出 警告 (非錯誤)：warning: [deprecation] ... has been deprecated
• IDE (IntelliJ/Eclipse) 會以劃線、灰顏色、工具提示警示開發者
• 運行期無任何影響，僅屬文檔與靜態分析層面

二、傳遞性實測：子類是否自動獲得警告？

測試代碼

@Deprecated
class Parent { public void doSomething() {} }

class Child extends Parent {
    @Override public void doSomething() {} // 重寫父類方法
}

public class Test {
    public static void main(String[] args) {
        Child c = new Child();
        c.doSomething(); // 編譯/IDE 是否警告？
    }
}

結果

三、結論：@Deprecated 不具備繼承傳遞性

1. 註解本身不會被繼承：Java 註解預設 @Inherited 僅作用於類層級的註解查詢 (clazz.isAnnotationPresent())，不影響方法/欄位。
2. 編譯器檢查邏輯：僅檢查調用點解析出的具體方法/構造子是否帶有 @Deprecated，不遞歸檢查父類鏈。
3. 重寫方法「切斷」警告：子類重寫後，調用點綁定至子類方法，父類註解不再可見。

四、最佳實踐建議

1. 遷移期雙重標記：父類方法加 @Deprecated，子類重寫方法同樣加上@Deprecated，並用 @Override 確保確實重寫。
2. 配合 Javadoc：@deprecated 說明替代方案、遷移時間表、移除版本，IDE 會顯示在工具提示中。
3. 靜態分析工具加強：SpotBugs、Error Prone、SonarQube 可配置規則檢測「調用已棄用 API」並提升為錯誤。
4. 庫作者：發布新版本前用 jdeprscan 掃描專案，確認無意外殘留棄用調用。

@Deprecated(since = "1.8", forRemoval = true)
public void oldMethod() { ... }