Java 方法添加棄用註解 @Deprecated 實現刪除線效果

問題背景

在 IDE (IntelliJ IDEA / Eclipse) 中看到標準庫方法帶有**刪除線**，表示該方法已**棄用**，詢問如何在自定義方法上添加此效果。

標準解法：@Deprecated 註解

Java 官方提供 java.lang.Deprecated 註解，編譯器識別後會：

1. 在調用處顯示**刪除線**警告。
2. 生成 Javadoc 時標記為 Deprecated。
3. IDE 代碼提示顯示刪除線圖標。

基本用法

/**
 * 計算兩數和
 * @deprecated 请使用 {@link #add(long, long)} 替代，支持更大數值範圍
 */
@Deprecated
public int add(int a, int b) {
    return a + b;
}

// 推薦替代方法
public long add(long a, long b) {
    return a + b;
}

進階：配合 @deprecated Javadoc 標籤 (強烈推薦)

/**
 * 獲取用戶名
 * 
 * @deprecated 此方法不再安全，請使用 {@link #getUserNameSecure()}。
 *             將在 v3.0 版本中移除。
 * @return 用戶名
 * @see #getUserNameSecure()
 */
@Deprecated
public String getUserName() {
    return this.name;
}

效果： 懸停方法時，IDE 會顯示完整的棄用原因、替代方案、移除版本計劃。

IDE 設置確認 (以 IntelliJ IDEA 為例)

若添加註解後無刪除線，檢查設置：

1. File → Settings → Editor → Inspections
2. 搜索 Deprecated，勾選 Deprecated API usage。
3. Severity 選 Warning (默認即可)。

Java 9+ 增強：@Deprecated(forRemoval=true, since="版本")

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

• forRemoval=true：明確將在未來版本**移除**，編譯器報警等級更高。
• since：標記從哪個版本開始棄用。

最佳實踐總結

1. **必加 @Deprecated** 註解 (編譯器識別關鍵)。
2. **必寫 Javadoc @deprecated** 標籤說明替代方案 (給人看的關鍵)。
3. 提供清晰的**遷移路徑** (新方法名、參數差異)。
4. 制定**移除時間表** (如 "v2.0 移除")，避免無限期棄用。