Mastering @Nullable: How to Use It on Methods, Fields, and Parameters

Many developers overlook the simple yet powerful @Nullable annotation. It can be placed on methods, fields, and parameters to indicate that the associated value may be null.

Method return values

When @Nullable precedes a method declaration, it signals that the method may return null. The following example demonstrates this usage in a Spring controller method:

@Nullable
public ApiResult upload(@NotNull(message = "#x4E0A#x4F20#x53C2#x6570#x4E0D#x80FD#x4E3A#x7A7A;") @RequestParam("file") MultipartFile[] file) throws BaseException {
    ApiResult apiResult = new ApiResult();
    SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyyMMdd");
    String format = simpleDateFormat.format(new Date());
    String realPath = filePath + File.separator + format;
    String returnPath = format;
    File targetFile = new File(realPath);
    if (!targetFile.exists()){
        targetFile.mkdirs();
    }
}

Here the @Nullable annotation tells callers that upload might return a null ApiResult.

Parameter nullability

Placing @Nullable before a parameter marks that argument as optional. The snippet below shows a method where the third argument op can be null:

private void checkUser(String fansid, String openid, @Nullable String op) throws BaseException{
    Consumer consumer = consumerService.selectByPrimaryKey(fansid);
    if (consumer == null) {
        throw new ParamException("#x7528#x6237#x4E0D#x5B58#x5728;");
    }
    Consumer consumer1 = consumerService.selectByPrimaryKey(openid);
    if(consumer1 == null){
        throw new ParamException("#x88AB#x5173#x6CE8#x8005#x4FE1#x606F#x5E38;");
    }
}

Adding @Nullable before op makes it clear that callers may pass a null value without causing a contract violation.

Field nullability

Annotating a class field with @Nullable indicates that the field may hold a null reference. In the following controller class, the isTime field is declared nullable:

@Validated
@RestController
@RequestMapping("miniapi/follow")
public class FollowController extends BaseController {
    @Nullable
    private String isTime;

    @Autowired
    private FollowService followService;
    @Autowired
    private ConsumerService consumerService;
    private Logger logger = LoggerFactory.getLogger(this.getClass());
}

This makes it explicit to developers and static analysis tools that isTime can be null.

Real‑world usage in Spring

The Spring utility class org.springframework.util.StringUtils uses @Nullable in its isEmpty method:

public static boolean isEmpty(@Nullable Object str) {
   return (str == null || "".equals(str));
}

The annotation documents that the method accepts a possibly null argument and handles it safely.

In summary, @Nullable is a straightforward annotation that can be applied to methods, parameters, and fields to convey nullability intent, improve code readability, and aid static analysis tools.