How JSR‑305 Annotations Boost Null‑Safety in Spring 5 and Mica Core

Explanation

Spring 5’s

spring-core

jar adds JSR‑305 related annotations, which are already heavily used throughout the Spring source code. The following image shows their usage in the framework.

JSR‑305 Introduction

Static analysis tools such as FindBugs, IntelliJ, Checkstyle, and PMD are widely used in Java development, but they struggle to capture certain API design decisions, like whether a value may be null or a number may be negative. While comprehensive APIs document these details in JavaDoc, analysis tools cannot detect them, leading to missed issues or false positives.

To address this, some tool developers introduced custom annotations (e.g., FindBugs and IntelliJ define their own @Nullable). Because these annotations differ, a standard was needed. JSR‑305, led by Bill Pugh, proposes a set of standard annotations for static analysis tools, covering nullability, sign, language, threading, and more.

For further details, see the JSR‑305 specification for software defect detection annotations.

Usage Scenarios

The goal of JSR‑305 is to help static analysis tools locate potential bugs early. These annotations are especially useful in foundational components and utility libraries, improving IDE hints and reducing bug risk. The

lutool 1.x

project copied Spring 5’s JSR‑305 annotations into its source, and the

mica – Spring Boot microservice core package

uses them via Spring Boot 2.1.x by importing the annotations from

spring‑core

.

Usage

Add Package‑Level Rules

1.

@NonNullFields

– indicates that fields are never null.

2.

@NonNullApi

– indicates that method parameters and return values are never null.

3. If package‑level non‑null is not desired, use

@NonNull

or

@Nullable

on individual elements.

Create a

package‑info.java

file with the following content:

<code>@NonNullApi
@NonNullFields
package net.dreamlu.mica.core.utils;
import org.springframework.lang.NonNullApi;
import org.springframework.lang.NonNullFields;</code>

After adding these annotations, the IDE provides null‑safety hints, as shown in the screenshots below.

@Nullable

Use

@Nullable

to mark fields, method parameters, or return values that may be null.

Parameter Can Be Null

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

Return Value Can Be Null

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

Field Can Be Null

<code>@Nullable
private String msg;</code>

References

[1] JSR‑305: Annotations for Software Defect Detection – https://link.juejin.im?target=http%3A%2F%2Fwww.infoq.com%2Fcn%2Fnews%2F2008%2F07%2Fjsr-305-update

[2] mica – Spring Boot microservice core package – https://link.juejin.im?target=https%3A%2F%2Fgitee.com%2F596392912%2Fmica