空值安全

雖然 Java 無法讓您透過其類型系統表達空值安全，但 Spring 框架在 org.springframework.lang 套件中提供了以下註解，讓您可以宣告 API 和欄位的可空性

  • @Nullable：註解，用於指示特定的參數、傳回值或欄位可以為 null。

  • @NonNull：註解，用於指示特定的參數、傳回值或欄位不能為 null（在套用 @NonNullApi 和 @NonNullFields 的參數、傳回值和欄位上不需要）。

  • @NonNullApi：套件層級的註解，宣告非空值為參數和傳回值的預設語意。

  • @NonNullFields：套件層級的註解，宣告非空值為欄位的預設語意。

Spring 框架本身利用了這些註解，但它們也可以在任何基於 Spring 的 Java 專案中使用，以宣告空值安全的 API 和（可選地）空值安全的欄位。目前尚不支援泛型類型引數、可變引數和陣列元素的可空性宣告。預計將在 Spring 框架版本之間（包括次要版本）微調可空性宣告。方法體內使用的類型的可空性不在本功能的範圍內。

其他常見的程式庫（例如 Reactor 和 Spring Data）提供了使用類似可空性安排的空值安全 API，為 Spring 應用程式開發人員提供一致的整體體驗。

使用案例

除了為 Spring 框架 API 可空性提供明確的宣告外，IDE（例如 IDEA 或 Eclipse）可以使用這些註解來提供與空值安全相關的有用警告，以避免在執行時發生 NullPointerException。

它們也用於使 Kotlin 專案中的 Spring API 具有空值安全性，因為 Kotlin 原生支援 空值安全。更多詳細資訊請參閱 Kotlin 支援文件。

JSR-305 元註解

Spring 註解使用 JSR 305 註解（一個休眠但廣泛使用的 JSR）進行元註解。JSR-305 元註解讓 IDEA 或 Kotlin 等工具供應商能夠以通用方式提供空值安全支援，而無需硬式編碼對 Spring 註解的支援。

為了利用 Spring 的空值安全 API，既沒有必要也不建議將 JSR-305 依賴項新增至專案類別路徑。只有在程式碼庫中使用空值安全註解的基於 Spring 的程式庫等專案才應新增 com.google.code.findbugs:jsr305:3.0.2 以及 compileOnly Gradle 配置或 Maven provided 範圍，以避免編譯器警告。