:::tips 这一章，完全没看懂要怎么用这个 :::

尽管 Java 不允许你用它的类型系统来表达 null-safety，但 Spring 框架现在在 org.springframework.lang 包中提供了以下注解，让你声明 API 和字段的nullability（无效、空 性质）。

  • @Nullable：注解，表明一个特定的参数、返回值或字段可以是空的。
  • @NonNull：注解，表明一个特定的参数、返回值或字段不能为空（在参数/返回值和字段上不需要，因为 @NonNullApi 和@NonNullFields 分别适用）。
  • @NonNullApi：包级的注解，声明非空为参数和返回值的默认语义。
  • @NonNullFields：在包一级的注解，声明非空为字段的默认语义。

Spring 框架本身就利用了这些注解，但它们也可以在任何基于 Spring 的 Java 项目中用来声明零安全的 API 和可选的零安全字段。目前还不支持通用类型参数、varargs 和数组元素的无效性，但在即将发布的版本中应该会支持，最新的信息请参见 SPR-15942。无效性声明有望在Spring Framework 的各个版本之间进行微调，包括小版本。方法体内部使用的类型的无效性不在此功能范围内。

:::info Reactor 和 Spring Data 等其他公共库提供了空安全 API，它们使用类似的空性安排，为 Spring 应用程序开发人员提供了一致的总体体验。 :::

使用案例

除了提供 Spring Framework API 无效性的明确声明外，这些注解还可以被 IDE（如 IDEA 或 Eclipse）用来提供与 null-safety 相关的有用警告，以避免在运行时出现 NullPointerException。

由于 Kotlin 原生支持 null-safety，它们也被用来在 Kotlin 项目中实现 Spring API 的 null-safe。更多细节可在 Kotlin 支持文档中找到。

JSR-305 元注解

Spring 注解是用 JSR 305 注解（一个休眠但广泛传播的 JSR）进行元注解的。JSR-305 元注解让 IDEA 或 Kotlin 等工具供应商以通用的方式提供空安全支持，而无需对 Spring 注释进行硬编码支持。

没有必要也不建议在项目 classpath 中添加 JSR-305 的依赖关系来利用 Spring 的空安全 API。只有基于 Spring 的库等项目在其代码库中使用 null-safety 注释时，才应在 Gradle 配置中添加 com.google.code.findbugs:jsr305:3.0.2的 compileOnly 或 Maven 提供的范围，以避免出现编译警告。