Spring 5 core 中的 @NonNull 是个什么鬼?!

素颜马尾好姑娘i 2022-02-14 12:07 267阅读 0赞

## 说明 ##

在`Spring 5`的 spring-core jar包中添加了 `jsr-305` 相关注解。在 `Spring` 源码中已经被大量使用。如下图：  
  
![001.png][]

## JSR-305介绍 ##

诸如 FindBugs、IntelliJ、Checkstyle 和 PMD 这样的静态分析工具在 Java 开发中得到了广泛应用。这些工具都很强大，但是有一些共同的问题它们都很难解决。在 API 的设计中，有一些决策是不言而喻的，比如何时值可以为 null，或者何时数字值不能为负。完备的 API 会将这些设计细节记录在 JavaDoc 之中，但是分析工具却无法发现类似细节，从而有可能将其忽略或是导致错误的检测结果。

为了解决这些问题，有些静态分析工具开发人员试图使用注解来定义相关细节。比如 FindBugs 和 IntelliJ 都定义了自己的注解，以表示方法何时返回 null。不过，这两个工具使用的注解有细微不同，也因此有了标准化的需求。由 FindBugs 创建人 Bill Pugh 带领制定的 JSR-305 标准，试图创建一套标准注解供分析工具使用，同时希望允许开发人员根据自己的需要添加额外的注解。当前提案中包括供判断是否为空、正负号、开发语言和线程等方面的众多注解。

更多jsr-305介绍请查看，[JSR-305：供检查软件缺陷用的注解][JSR-305]

## 使用场景 ##

由上文的介绍，我们知晓了 `jsr-305` 的目标：供检查软件缺陷用。方便静态代码检查工具及时查找出潜在的 bug。所以这些注解特别适合基础组件和工具包，增强 `IDE` 提示，减少潜在 `bug`。  
lutool 1.x 中复制了spring 5中的 `jsr-305` 相关注解到源码中，到 [mica - Spring boot 微服务开发核心包][mica - Spring boot] 由于依赖的 `Spring boot 2.1.x`，则直接使用 `spring core` 中的注解。

## 使用 ##

### 添加包级规则 ###

1.  `@NonNullFields`表示`Field`不为null。  
    
2.  `@NonNullApi`表示`方法参数`和`返回值`不为null。  
    
3.  对于不想使用包级别不为null，可直接使用`@NonNull`，使用方式同下文`@Nullable`。

在包下添加`package-info.java`，内容如下：

@NonNullApi
    @NonNullFields
    package net.dreamlu.mica.core.utils;
    import org.springframework.lang.NonNullApi;
    import org.springframework.lang.NonNullFields;

添加完该注解后编写代码时编辑器会给出提示，如下图：  
![002.png][]

![003.png][]

### `@Nullable` ###

对于部分可为空的`Field`、`方法参数`和`返回值`需要使用`@Nullable`进行标示。

#### 参数可为null ####

public static boolean isBlank(@Nullable final CharSequence cs) {
        return !StringUtils.hasText(cs);
    }

#### 返回值可为null ####

@Nullable
    public static String getCookieVal(HttpServletRequest request, String name) {
        Cookie cookie = getCookie(request, name);
        return cookie != null ? cookie.getValue() : null;
    }

#### 属性可为null ####

@Nullable
    private String msg;

## 开源推荐 ##

*  `mica` Spring boot 微服务核心组件集：[gitee.com/596392912/m…][mica - Spring boot]
 *  `Avue` 一款基于vue可配置化的神奇框架：[gitee.com/smallweigit…][gitee.com_smallweigit]
 *  `pig` 宇宙最强微服务（架构师必备）：[gitee.com/log4j/pig][gitee.com_log4j_pig]
 *  `SpringBlade` 完整的线上解决方案（企业开发必备）：[gitee.com/smallc/Spri…][gitee.com_smallc_Spri]
 *  `IJPay` 支付SDK让支付触手可及：[gitee.com/javen205/IJ…][gitee.com_javen205_IJ]

[001.png]: /images/20220214/d8257d82a45540759fe16a7322cb8738.png
[JSR-305]: https://link.juejin.im?target=http%3A%2F%2Fwww.infoq.com%2Fcn%2Fnews%2F2008%2F07%2Fjsr-305-update
[mica - Spring boot]: https://link.juejin.im?target=https%3A%2F%2Fgitee.com%2F596392912%2Fmica
[002.png]: /images/20220214/18f25154084d43bba192b4b324204d18.png
[003.png]: /images/20220214/97fc7d279e3148238eb2cc2abb882d9f.png
[gitee.com_smallweigit]: https://link.juejin.im?target=https%3A%2F%2Fgitee.com%2Fsmallweigit%2Favue
[gitee.com_log4j_pig]: https://link.juejin.im?target=https%3A%2F%2Fgitee.com%2Flog4j%2Fpig
[gitee.com_smallc_Spri]: https://link.juejin.im?target=https%3A%2F%2Fgitee.com%2Fsmallc%2FSpringBlade
[gitee.com_javen205_IJ]: https://link.juejin.im?target=https%3A%2F%2Fgitee.com%2Fjaven205%2FIJPay