仓库方法的空值处理

返回单个聚合实例的 Repository CRUD 方法可以使用 Optional 来表示值可能不存在。 除此之外，Spring Data 还支持在查询方法中返回以下包装类型：spring-doc.cadn.net.cn

或者，查询方法也可以完全不使用包装类型。 此时，查询结果不存在将通过返回 null 来表示。 返回集合、集合替代类型、包装类型和流的 Repository 方法保证永远不会返回 null，而是返回相应的空表示形式。 详情请参见“Repository 查询返回类型”。spring-doc.cadn.net.cn

可空性注解

JSpecify

从 Spring Framework 7 和 Spring Data 4 开始，您可以使用 JSpecify 来表达仓库方法的可空性约束。 JSpecify 与 IntelliJ 和 Eclipse 深度集成，提供对工具友好的方式，并可在运行时选择性地进行 null 检查，如下所示：spring-doc.cadn.net.cn

通过 @NullMarked 文件在包级别上使用 package-info.java
@NullMarked
package org.springframework.core;

import org.jspecify.annotations.NullMarked;

在属于该包的各种 Java 文件中，可空类型的使用通过 @Nullable 显式定义。 建议将该注解放在相关类型之前指定。spring-doc.cadn.net.cn

例如，对于一个字段：spring-doc.cadn.net.cn

private @Nullable String fileEncoding;

或者用于方法参数和返回值：spring-doc.cadn.net.cn

public static @Nullable String buildMessage(@Nullable String message,
                                            @Nullable Throwable cause) {
    // ...
}

重写方法时，可空性注解不会从父类方法中继承。 这意味着，如果你只是想重写实现并保持相同的 API 可空性，就应该重复这些可空性注解。spring-doc.cadn.net.cn

对于数组和可变参数（varargs），你需要能够区分数组元素的可空性与数组本身的可空性。 请注意 Java 规范中定义的语法，这乍看之下可能会令人感到意外：spring-doc.cadn.net.cn

  • @Nullable Object[] array 表示数组中的各个元素可以为 null，但数组本身不能为 null。spring-doc.cadn.net.cn

  • Object @Nullable [] array 表示数组中的各个元素不能为 null，但数组本身可以为 null。spring-doc.cadn.net.cn

  • @Nullable Object @Nullable [] array 表示数组中的各个元素以及数组本身都可以为 null。spring-doc.cadn.net.cn

Java 规范还强制要求，像 JSpecify 的 @Target(ElementType.TYPE_USE) 这样使用 @Nullable 定义的注解，在用于内部类或全限定类型时，应放在最后一个 . 之后：spring-doc.cadn.net.cn

@NonNull 和 @NullUnmarked 在典型使用场景中很少需要。spring-doc.cadn.net.cn

Spring 框架的可空性与 JSR-305 注解

你可以通过使用Spring Framework 的可空性注解来为仓库方法表达可空性约束。spring-doc.cadn.net.cn

从 Spring Framework 7 开始，Spring 的可空性注解已被弃用，建议改用 JSpecify。 有关更多信息，请参阅框架文档中的从 Spring 空安全注解迁移到 JSpecify。

它们提供了一种对工具友好的方法，并在运行时选择性地进行 null 检查，如下所示：spring-doc.cadn.net.cn

Spring 注解使用 JSR 305 注解（一项虽已停滞但被广泛使用的 JSR）进行了元注解。 JSR 305 元注解使工具提供商（如 IDEA、Eclipse 和 Kotlin）能够以通用方式提供空安全支持，而无需对 Spring 注解进行硬编码支持。 要为查询方法启用可空性约束的运行时检查，您需要在包级别通过在 @NonNullApi 中使用 Spring 的 package-info.java 来激活非空性，如下例所示：spring-doc.cadn.net.cn

在 package-info.java 中声明非空性

一旦启用了非空默认设置，存储库查询方法的调用将在运行时根据可空性约束进行验证。 如果查询结果违反了所定义的约束，则会抛出异常。 这种情况发生在方法本应返回 null，但被声明为非空（即在存储库所在包上定义的注解所指定的默认行为）时。 如果您希望再次允许某些方法返回可空结果，请在个别方法上选择性地使用 @Nullable 注解。 本节开头提到的结果包装类型仍按预期正常工作：空结果将被转换为代表“缺失”的值。spring-doc.cadn.net.cn

以下示例展示了上述多种技术：spring-doc.cadn.net.cn

使用不同的可空性约束
package com.acme;                                                       (1)

import org.springframework.lang.Nullable;

interface UserRepository extends Repository<User, Long> {

  User getByEmailAddress(EmailAddress emailAddress);                    (2)

  @Nullable
  User findByEmailAddress(@Nullable EmailAddress emailAddress);          (3)

  Optional<User> findOptionalByEmailAddress(EmailAddress emailAddress); (4)
}
1 该仓库位于一个我们已定义非空行为的包（或子包）中。
2 当查询未产生结果时，抛出 EmptyResultDataAccessException。 当传递给该方法的 IllegalArgumentException 为 emailAddress 时，抛出 null。
3 当查询未产生结果时，返回 null。 同时也接受 null 作为 emailAddress 的值。
4 当查询未产生结果时，返回 Optional.empty()。 当传入方法的 IllegalArgumentException 为 emailAddress 时，抛出 null。

基于 Kotlin 的仓库中的可空性

Kotlin 在语言层面内置了可空性约束的定义。 Kotlin 代码被编译为字节码，该字节码不会通过方法签名来表达可空性约束，而是通过编译进来的元数据来实现。 请确保在项目中包含 kotlin-reflect JAR，以启用对 Kotlin 可空性约束的内省。 Spring Data 仓库利用该语言机制来定义这些约束，从而执行相同的运行时检查，如下所示：spring-doc.cadn.net.cn

在 Kotlin 仓库上使用可空性约束
interface UserRepository : Repository<User, String> {

  fun findByUsername(username: String): User     (1)

  fun findByFirstname(firstname: String?): User? (2)
}
1 该方法将参数和返回值都定义为不可为空（Kotlin 的默认行为）。 Kotlin 编译器会拒绝向该方法传入 null 的调用。 如果查询结果为空，则会抛出 EmptyResultDataAccessException 异常。
2 此方法接受 null 作为 firstname 参数的值，并且如果查询未产生结果，则返回 null。