此版本仍在开发中，尚未被视为稳定版本。如需最新稳定版本，请使用 Spring Data Cassandra 5.0.4！spring-doc.cadn.net.cn

仓库方法的空值处理

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

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

可空性注解

你可以通过使用Spring Framework 的可空性注解来为仓库方法表达可空性约束。 它们提供了一种对工具友好的方式，并在运行时选择性地进行 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。