Null-safety

尽管 Java 无法让你用其类型系统表示空安全性，但 Spring Framework 提供了 org.springframework.lang 包中的以下注释，让你声明 API 和字段的空值性：

Although Java does not let you express null-safety with its type system, the Spring Framework provides the following annotations in the org.springframework.lang package to let you declare nullability of APIs and fields:

  • @Nullable: Annotation to indicate that a specific parameter, return value, or field can be null.

  • @NonNull: Annotation to indicate that a specific parameter, return value, or field cannot be null (not needed on parameters, return values, and fields where @NonNullApi and @NonNullFields apply, respectively).

  • @NonNullApi: Annotation at the package level that declares non-null as the default semantics for parameters and return values.

  • @NonNullFields: Annotation at the package level that declares non-null as the default semantics for fields.

Spring Framework 本身利用了这些注释，但它们也可以在任何基于 Spring 的 Java 项目中使用，以声明 null 安全 API 和可选的 null 安全字段。暂不支持泛型类型参数、变长参数和数组元素的空值声明。预计空值声明将在 Spring Framework 的版本之间进行微调，包括次要版本。方法体中使用的类型的空值不在此功能的范围内。

The Spring Framework itself leverages these annotations, but they can also be used in any Spring-based Java project to declare null-safe APIs and optionally null-safe fields. Nullability declarations for generic type arguments, varargs, and array elements are not supported yet. Nullability declarations are expected to be fine-tuned between Spring Framework releases, including minor ones. Nullability of types used inside method bodies is outside the scope of this feature.

其他常见库（如 Reactor 和 Spring Data）提供了使用类似空值安排的空安全 API，为 Spring 应用程序开发人员提供了始终如一的整体体验。

Other common libraries such as Reactor and Spring Data provide null-safe APIs that use a similar nullability arrangement, delivering a consistent overall experience for Spring application developers.

Use cases

除了为 Spring Framework API 空值提供明确的声明之外，这些注释还可由 IDE（如 IDEA 或 Eclipse）使用，以提供有关 null 安全性的有用警告，从而避免在运行时出现 NullPointerException。

In addition to providing an explicit declaration for Spring Framework API nullability, these annotations can be used by an IDE (such as IDEA or Eclipse) to provide useful warnings related to null-safety in order to avoid NullPointerException at runtime.

它们还用于在 Kotlin 项目中使 Spring API 具有 null 安全性，因为 Kotlin 本机支持 null 安全性。更多详细信息可在 Kotlin 支持文档中找到。

They are also used to make Spring APIs null-safe in Kotlin projects, since Kotlin natively supports null-safety. More details are available in the Kotlin support documentation.

JSR-305 meta-annotations

Spring 注释使用 https://www.jcp.org/en/jsr/detail?id=305 注释（一种休眠但广泛使用的 JSR）进行元注释。JSR-305 元注释允许诸如 IDEA 或 Kotlin 的工具供应商以通用方式提供 null 安全支持，而无需为 Spring 注释硬编码支持。

Spring annotations are meta-annotated with JSR 305 annotations (a dormant but widespread JSR). JSR-305 meta-annotations let tooling vendors like IDEA or Kotlin provide null-safety support in a generic way, without having to hard-code support for Spring annotations.

不必也不建议将 JSR-305 依赖项添加到项目的类路径，以利用 Spring 的 null 安全 API。只有在代码库中使用 null 安全注释的项目（例如基于 Spring 的库）才应使用 com.google.code.findbugs:jsr305:3.0.2 添加 compileOnly Gradle 配置或 Maven provided 范围，以避免编译器警告。

It is neither necessary nor recommended to add a JSR-305 dependency to the project classpath to take advantage of Spring’s null-safe APIs. Only projects such as Spring-based libraries that use null-safety annotations in their codebase should add com.google.code.findbugs:jsr305:3.0.2 with compileOnly Gradle configuration or Maven provided scope to avoid compiler warnings.