使用空值註釋

NullPointerException 是 Java 程式失敗最常見的原因之一。 在最簡單的情況下,編譯器在發現如下的程式碼時可以直接警告您:

    Object o = null;
    String s = o.toString();

在分支/迴圈及擲出異常狀況下,為了查明在程式的某些或全部路徑上,是否已指派空值/非空值給解除參照的變數,相當複雜的流程分析就變得有必要。

由於先天的複雜性,最好在小片段中執行流程分析。 一次分析一個方法可以在良好的工具效能情況下完成 - 而系統全面分析已超出 Eclipse Java 編譯器的範圍。 優點是:分析快速,可漸進地完成,編譯器可隨著您輸入而直接警告您。 缺點:分析無法「看見」哪些值(空值或非空值)在方法之間流動(參數和回覆值)。

程序間的空值分析

這是空值註釋發揮作用的地方。 您可以將方法參數指定為 @NonNull,告知編譯器在這個位置中不要空值。

    String capitalize(@NonNull String in) {
        return in.toUpperCase();                // 不需要空值檢查
    }
    void caller(String s) {
        if (s != null)
            System.out.println(capitalize(s));  // 需要先前的空值檢查
    }

以 Design-by-Contract 風格來說,這分成兩方面:

  1. 呼叫端負責永不傳遞空值,這由明確空值檢查來確定。
  2. 方法 capitalize 的實作者享有保證引數 in 不應該為空值,因此在這裡未經空值檢查而解除參照不會有問題。

對於方法回覆值,狀況是對稱的:

    @NonNull String getString(String maybeString) {
        if (maybeString != null)
            return maybeString;                         // 需要上述空值檢查
    else
            return "<n/a>";
    }
    void caller(String s) {
        System.out.println(getString(s).toUpperCase()); // 不需要空值檢查
    }
  1. 現在實作者必須確保永不傳回空值。
  2. 相反地,呼叫端現在享有保證未經檢查而解除參照方法結果沒有問題。

可用的註釋

Eclipse Java 編譯器可以配置來使用其加強型空值分析(依預設停用)的三個不同註釋類型:

這些位置中支援註釋 @NonNull 和 @Nullable:

以下支援 @NonNullByDefault

請注意,即使這些註釋的實際完整名稱可配置,但依預設會使用上述註釋(從套件 org.eclipse.jdt.annotation 中)。

建置路徑設定

Eclipse 的 eclipse/plugins/org.eclipse.jdt.annotation_*.jar 中隨附了一個內含預設空值註釋的 JAR。 在編譯時期,這個 JAR 必須位於建置路徑上,但在執行時期並不需要(所以您不需要將這個 JAR 傳送給已編譯程式碼的使用者)。

以下是針對將 JAR 新增至建置路徑之 @NonNull、@Nullable 或 @NonNullByDefault 等無法解析的參照,所提供的兩個快速修正程式:

空值註釋的解譯

現在應該很清楚空值註釋可以為 Java 程式增加更多資訊(再由編譯器用來提供較佳的警告)。 但我們真正希望這些註釋有何用途? 從實務觀點來看,我們想用空值註釋來表達的資訊至少有三個層次:

  1. 對讀者的偶然提示(真人和編譯器)
  2. 依合約設計:某些或全部方法的 API 規格
  3. 使用延伸類型系統的完整規格

以 (1) 來說,您可以立即開啟使用空值註釋,不必進一步閱讀,但您不應預期現在和之後會看到更多提示。 其他層次需要進一步說明。

依合約設計:API 規格

乍看之下,以「依合約設計」風格來說,API 規格使用空值註釋只表示所有 API 方法的簽章應該完全標註,亦即,不考慮 int 之類的初始類型,每一個參數和每一個方法傳回類型都應該標示為 @NonNull 或 @Nullable。 因為這表示要插入大量空值註釋,最好瞭解在設計良好的程式碼中(尤其是 API 方法),@NonNull 比 @Nullable 更常用。因此,可將 @NonNull 宣告為 default,在套件層次上使用 @NonNullByDefault 註釋,以減少註釋數目。

請注意,@Nullable 和省略空值註釋之間的明顯差異: 這個註釋明確表示空值沒問題,且必須在預期內。 相反地,沒有註釋只是表示我們不知道用意。 這是長期以來的狀況,雙方(呼叫端和被呼叫端)重複檢查空值,有時是雙方誤以為對方會執行檢查。 這是 NullPointerExceptions 的來源。 如果沒有註釋,編譯器不會提供特定的建議,但如果使用 @Nullable 註釋,則會標示每一個未檢查的解除參照。

根據這些基礎,我們可以將所有參數註釋對映至前置條件,並將傳回註釋解譯成方法的後置條件。

子類型和置換

在物件導向程式設計中,「依合約設計」的概念還需要說明一個方面: 子類型和置換(在後文中,「置換」就代表 Java 6 的 @Override 註釋:從超類型置換或實作另一個方法的方法)。呼叫方法的用戶端如下:

    @NonNull String checkedString(@Nullable String in)

應該允許假設這個方法的所有實作滿足合約。 因此,在介面 I1 中發現方法宣告時,我們必須排除任何實作 I1 的類型 Cn 提供不相容實作。 明確地說,如果有任何 Cn 嘗試以將參數宣告為 @NonNull 的實作來置換這個方法,都是不合法。 如果我們願意允許這樣,則針對 I1 所設計的用戶端模組可以合法地傳遞空值當作引數,但實作會假設非空值 - 允許方法實作內未檢查的解除參照,但在執行時期會爆發問題。 因此,@Nullable 參數規格強制所有置換,以允許空值為預期的合法值。

相反地,@NonNull 傳回規格強制所有置換,以確保永不傳回空值。

因此,編譯器必須檢查沒有置換會新增不存在於超類型中的 @NonNull 參數註釋 (或 @Nullable 傳回註釋)。

很有趣的是反向重新定義合法:新增 @Nullable 參數註釋或 @NonNull 傳回註釋(您可以將這些視為方法的「改進」,它接受更多值且產生更明確的回覆值)。

舊式超類型

當標註的程式碼撰寫成「舊式」(即未標註)類型(可能來自協力廠商程式庫,因此無法變更)的子類型時,先前考量增加困難度。 如果您仔細閱讀前一節,您會發現我們不允許「舊式」方式被置換為具有 @NonNull 參數的方法 (因為使用超類型的用戶端不會「看到」@NonNull 契約)。

在此情況下,將強制您省略空值註釋 (已計劃支援事後將註釋新增至程式庫,但尚無法保證是否及何時提供這種特性)。

取消空值預設值

如果「舊式」類型的子類型位於已指定 @NonNullByDefault 的套件中,情況會變得難以處理。現在,未標註超類型的類型需要將置換方法中的所有參數標示為 @Nullable: 甚至不允許省略參數註釋,因為這樣會解譯成 @NonNull 參數,而在該位置中禁止如此。 這就是 Eclipse Java 編譯器支援取消空值預設值的原因: 這個元素會取消將具有 @NonNullByDefault(false) 的方法或類型標註成適用的預設值,而未標註的參數會再次解譯成未指定。 現在,子類型又重回到舊式,未新增不需要的 @Nullable 註釋:

class LegacyClass {
    String enhance (String in) { // 不強制用戶端傳遞非空值。
        return in.toUpperCase();
    }
}
 
@NonNullByDefault
class MyClass extends LegacyClass {
	
    // ... 具有 @NonNull 預設值的方法 ...
 
    @Override
    @NonNullByDefault(false)
    String enhance(String in) { // 如果 @NonNullByDefault 在這裡有作用,則此行無效
        return super.enhance(in);
    }
}

依合約設計的好處

在上述「依合約設計」樣式中使用空值註釋,在幾方面有助於改進 Java 程式碼的品質: 在方法之間的介面上,更明確看出哪些參數/傳回允許空值及哪些不允許。 這可透過也可讓編譯器檢查的方式來捕捉設計決策,與開發人員相當有關。

此外,根據這個介面規格,程序內的流程分析可取得可用的資訊,提供更準確的錯誤/警告。 如果沒有註釋,則進出方法的任何值會有不明的空值,因此空值分析仍然不會指出其使用情形。 如果有 API 層次空值註釋,則實際可知大部分值的空值,而編譯器未注意的 NPE 極少。 不過,您應該注意仍有漏洞,由於未指定的值會流進分析,而無法執行完成陳述式,不論執行時期是否可能發生 NPE。

使用延伸類型系統的完整規格

空值註釋的支援設計符合未來的延伸,所以編譯器將可保證認證的程式絕不會在執行時期擲出 NullPointerException(例如反射等未檢查的部分的一般警告)。 關於未來的延伸,尚無法做出任何保證,基本上只是在既有的解譯外提出不同的解譯。

我們將空值註釋解譯成類型系統的一部分,使給定的程式中有更多類型: 以任何給定的類別 Cn 而言,類別本身不再視為舊式類型,只有 "@NonNull Cn" 和 "@Nullable Cn" 是有用的類型。基本上,對於程式中的每一個值,我們會知道是否可為空值(且在解除參照之前必須檢查)。 如果排除第三個選項(未標註的類型),則編譯器可以嚴格標示每一個不安全用法。

關於這個目標,現行實作有兩個主要限制:

從現在起,不論現行限制如何,完整指定和完全檢查的程式已具有一些連帶作用,形成現行分析和編譯器所報告的錯誤/警告。 我們將說明細節,解釋編譯器所檢查的規則及違反規則時發出的訊息。

解釋編譯器訊息

在對應的喜好設定頁面,編譯器檢查的個別規則依下列標題分組:

空值規格的違規

在規格違規方面,我們會處理空值註釋的要求違反實際實作的任何狀況。 一般狀況是指定的值(區域、引數、方法傳回)為 @NonNull,而實作實際上提供可為空值的值。 在這裡,如果確實知道表示式會評估為 null 值,或如果以 @Nullable 註釋來宣告,則表示式視為可為空值。

其次,這一組也包含如上討論的方法置換的規則。 在這裡,超方法會建立要求(例如,空值為合法引數),而置換會嘗試躲避這個要求(假設空值不是合法引數)。 如前所述,就算將引數從未標註特殊化為 @NonNull 也違反規格,因為這樣會引進合約來約束用戶端(不傳遞空值),但使用超類型的用戶端根本不知有這個合約,所以根本不知如何處理。

這裡提供規格違規的完整狀況清單。 必須瞭解不應該忽略這一組的錯誤,否則會根據錯誤的假設來執行整個空值分析。 明確地說,每當編譯器看到具有 @NonNull 註釋的值時,就可確定不會在執行時期出現空值。 這是關於規格違規的規則,可確保這個推論很合理。 因此,強烈建議將這種問題維持配置為錯誤。

空值註釋與空值推斷之間發生衝突

這一組規則也會檢查是否遵循空值規格。 不過,我們在這裡處理的不是宣告為 @Nullable 的值 (也不是 null 值本身),而是程序內流程分析推斷在某些執行路徑上可能出現空值的值。

這個狀況起因於在未標註的區域變數上,編譯器會使用流程分析來推斷是否可能有空值。 假設這項分析正確,如果發現問題,則這個問題的嚴重性與直接違反空值規格相同。 因此,再次強烈建議將這個問題維持配置為錯誤,不要忽略這些訊息。

將這些問題分組有兩個目的:利用流程分析來記錄已發生給定的問題,以及:考量這個流程分析可能錯誤的情況(因為實作有誤)。 如果確認是實作錯誤,則在異常狀況下可以抑制這種錯誤訊息。

以任何靜態分析的本質而言,流程分析可能看不出不可能有執行路徑和值的某些組合。以變數相關性來舉例說明:

   String flatten(String[] inputs1, String[] inputs2) { 
        StringBuffer sb1 = null, sb2 = null;
        int len = Math.min(inputs1.length, inputs2.length);
        for (int i=0; i<len; i++) {
            if (sb1 == null) {
                sb1 = new StringBuffer();
                sb2 = new StringBuffer();
            }
            sb1.append(inputs1[i]);
            sb2.append(inputs2[i]); // 在這裡警告
        }
        if (sb1 != null) return sb1.append(sb2).toString();
        return "";
    }

編譯器會報告 sb2.append(..) 的呼叫上可能有空值指標存取. 讀者可看到沒有實際的危險,因為 sb1 和 sb2 實際上是以兩個變數皆為空值或兩者皆不為空值的方式產生關聯。 我在問題的那一行,我們知道 sb1 不是空值,因此 sb2 也不是空值。 我們不深入探討相關性分析為何超出 Eclipse Java 編譯器功能的詳細原因,只要記住,這項分析沒有完整定理證明的能力,因此只是悲觀地報告某些問題,而更強大的分析可能將這些問題視為假警報。

如果您要利用流程分析,建議您稍微協助編譯器來「看見」您的結論。 這項協助可以只是將 if (sb1 == null) 分割成兩個獨立的 if,每一個區域變數各一個,只要付出極低的代價,現在編譯器就可確實瞭解狀況,並據以檢查程式碼。 本主題的更多討論如下。

未檢查從非標註類型轉換成 @NonNull 類型

這一組問題是基於下列類推方法來論證:在使用 Java 5 通用類型的程式中,呼叫 Java-5 之前的程式庫可能會公開原始類型,也就是通用類型的應用程式(無法指定具體類型引數)。 為了將這些值傳入使用通用類型的程式中,編譯器可以新增隱含轉換,假設類型引數是以程式碼的用戶端部分所預期的方式來指定。 編譯器會對使用這種轉換發出警告,並假設程式庫「做對事」來繼續其類型檢查。 同樣地,程式庫方法未標註的傳回類型可以視為「原始」或「舊式」類型。 再者,隱含轉換可以樂觀地假設預期的規格。 此外會發出警告,而分析會繼續假設程式庫「做對事」。

理論上,需要這種隱含轉換也表示規格違規。 不過,在此情況下,可能是協力廠商程式碼違反我們的程式碼所預期的規格。 或者,可能是(我們本身已確認)某些協力廠商程式碼履行合約,但卻沒有如此宣告(因為沒有使用空值註釋)。 在此情況下,我們可能無法準確修復組織原因的問題。

    @SuppressWarnings("null")
    @NonNull Foo foo = Library.getFoo(); // 隱含轉換
    foo.bar(); 

上述程式碼片段假設 Library.getFoo() 傳回 Foo 而未指定空值註釋。 我們可以指派給 @NonNull 區域變數,以觸發未檢查轉換的警告,將回覆值整合到標註的程式內。 將對應的 SuppressWarnings("null") 新增至這個宣告,表示我們知道先天的危險,並負責驗證程式庫的行為確實符合預期。

讓程式碼更易於分析的提示

如果流程分析看不到某個實際上不是空值的值,最簡單的策略就是新增以 @NonNull 標註的範圍區域變數。 然後,如果您確信指派給這個區域變數的值在執行時期絕不會是空值,則您可以使用如下的 helper 方法:

    static @NonNull <T> T assertNonNull(@Nullable T value, @Nullable String msg) {
        if (value == null) throw new AssertionError(msg);
        return value;
    }
    @NonNull MyType foo() {
        if (isInitialized()) {
            MyType couldBeNull = getObjectOrNull();
            @NonNull MyType theValue = assertNonNull(couldBeNull, 
                    "value should not be null because application " +
                    "is fully initialized at this point.");
            return theValue;
        }
        return new MyTypeImpl();
    }

請注意,使用上述 assertNonNull() 方法表示您要負責在執行時期一律遵守這項主張。 就算這不是您要的,標註的區域變數仍有助於分析將空值可能進入某位置的範圍和原因縮小。

採用空值註釋的提示

當 JDT 3.8.0 版發行時,仍持續收集採用空值註釋的建議。因此,這項資訊目前在 Eclipse Wiki 中維護。