https://docs.spring.io/spring-framework/reference/core/null-safety.html
虽然Java的类型系统不允许你表达空值安全(null-safety),但Spring框架在org.springframework.lang
包中提供了以下注解,让你能够声明API和字段的空值性(nullability ):
@Nullable
:注解,用于指示特定的参数、返回值或字段可以为null
。@NonNull
:注解,用于指示特定的参数、返回值或字段不能为null
(当@NonNullApi
和@NonNullFields
分别应用于参数、返回值和字段时,不需要此注解)。@NonNullApi
:包级别的注解,用于声明参数和返回值的默认语义为非null
。@NonNullFields
:包级别的注解,用于声明字段的默认语义为非null
。
Spring框架本身利用了这些注解,但它们也可以用于任何基于Spring的Java项目中,以声明空值安全的API和可选的空值安全字段。目前尚不支持泛型类型参数、可变参数和数组元素的空值性声明。预计空值性声明将在Spring框架的各个版本(包括次要版本)之间进行微调。方法体内部使用的类型的空值性不在此功能范围内。
其它常见的库,如Reactor和Spring Data,也提供了使用类似空值性安排的空值安全API,为Spring应用程序开发人员提供了一致的整体体验。
用例
除了为Spring框架API的空值性提供明确的声明之外,这些注解还可以被集成开发环境(如IDEA或Eclipse)用于提供与空值安全性相关的有用警告,以避免在运行时出现空指针异常(NullPointerException
)。
由于 Kotlin 本身支持空值安全性,因此这些注解也用于使 Kotlin 项目中的 Spring API 具有空值安全性。
JSR-305元注解(meta-annotations)
Spring注解使用JSR 305注解进行了元注解(meta-annotated)。JSR-305是一个休眠但广泛使用的JSR。JSR-305元注解允许像IDEA或Kotlin这样的工具供应商以通用的方式为Spring注解提供空值安全性支持,而无需对Spring注解进行硬编码支持。
为了利用Spring的空安全API,既不必要也不推荐将JSR-305依赖项添加到项目类路径中。只有那些在代码库中使用空安全性注解的基于Spring的库项目,才应该使用Gradle的compileOnly
配置或Maven的provided
范围添加com.google.code.findbugs:jsr305:3.0.2
,以避免编译器警告。