Spring 框架
API
Spring 框架
API

(#null-safety)7. Null 安全

预计阅读时间: 5 分钟

Although Java does not let you express null-safety with its type system, the Spring Framework now provides the following annotations in the org.springframework.lang package to let you declare nullability of APIs and fields:
尽管 Java 的类型系统不允许您用其类型系统表达空安全性，但 Spring 框架现在在 org.springframework.lang 包中提供了以下注解，以便您声明 API 和字段的空可性：

  • @Nullable: Annotation to indicate that a specific parameter, return value, or field can be null.
    @Nullable ：注释以表明特定参数、返回值或字段可以是 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).
    @NonNull ：注释表示特定参数、返回值或字段不能 null （当 @NonNullApi 和 @NonNullFields 适用时，参数/返回值和字段不需要 null ）。

  • @NonNullApi: Annotation at the package level that declares non-null as the default semantics for parameters and return values.
    @NonNullApi ：在包级别声明参数和返回值默认语义为非空的注释。

  • @NonNullFields: Annotation at the package level that declares non-null as the default semantics for fields.
    @NonNullFields ：在包级别声明字段默认语义为非空的注释。

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.
Spring 框架本身利用了这些注解，但它们也可以在任何基于 Spring 的 Java 项目中用来声明无 null 安全的 API 和可选的无 null 安全字段。
Generic type arguments, varargs and array elements nullability are not supported yet but should be in an upcoming release, see SPR-15942 for up-to-date information. Nullability declarations are expected to be fine-tuned between Spring Framework releases, including minor ones. Nullability of types used inside method bodies is outside of the scope of this feature.
泛型类型参数、可变参数和数组元素的可空性目前尚不支持，但将在即将发布的版本中提供，请参阅 SPR-15942 获取最新信息。预计可空性声明将在 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.
其他常见库，如 Reactor 和 Spring Data，提供了使用类似不可为空的 API，为 Spring 应用程序开发者提供一致的总体体验。

(#use-cases)7.1. Use cases 7.1. 应用场景

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.
除了为 Spring Framework API 的 nullability 提供显式声明外，这些注解还可以被 IDE（如 IDEA 或 Eclipse）用来提供有关 null 安全性的有用警告，以避免在运行时出现 NullPointerException 。

They are also used to make Spring API null-safe in Kotlin projects, since Kotlin natively supports null-safety. More details are available in the Kotlin support documentation.
它们也用于使 Kotlin 项目中的 Spring API 具有空安全，因为 Kotlin 本地支持空安全。更多详细信息可在 Kotlin 支持文档中找到。

(#jsr-305-meta-annotations)7.2. JSR-305 meta-annotations

7.2. JSR-305 元注解

Spring annotations are meta-annotated with JSR 305 annotations (a dormant but wide-spread 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.
Spring 注解通过 JSR 305 注解（一个休眠但广泛使用的 JSR）进行元注解。JSR-305 元注解允许 IDEA 或 Kotlin 等工具供应商以通用方式提供空值安全性支持，而无需硬编码对 Spring 注解的支持。

It is not necessary nor recommended to add a JSR-305 dependency to the project classpath to take advantage of Spring null-safe API. 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 compile warnings.
没有必要也不建议将 JSR-305 依赖添加到项目类路径中，以利用 Spring 的空安全 API。只有像基于 Spring 的库这样的项目，在其代码库中使用空安全注解，才应该通过 com.google.code.findbugs:jsr305:3.0.2 Gradle 配置或 Maven compileOnly 范围添加 provided ，以避免编译警告。