JSpecify

JSpecify 是 Java 生态中用于标准化 Null 安全性（Null-Safety）的一套的注解和规范。

IntelliJ IDEA 2025.3+ 以及静态分析工具能够通过这些注解，在编译期间就发现潜在的 NullPointerException。

Specify 的核心注解

@NullMarked：最核心注解；通常放在包级别（package-info.java）或类级别；用于声明该范围内的所有类型默认都不允许为 null；

@Nullable：显式标记某个字段、参数或返回值可以为 null。这是在 @NullMarked 范围内的唯一“例外”；

@NullUnmarked：用于对特定类或方法禁用 Null 安全检查，通常用于兼容旧代码。

最佳实践示例

// 1. 在 package-info.java 中开启包级默认非空检查
@NullMarked
package com.example.project;


// 2. 在业务代码中使用
public record UserProjection(
    Long id, 
    String username, 
    @Nullable String middleName // 明确告诉 MyBatis 和 IDE，中间名可能为空
) {}

编译期预警：如果代码里没判空就调用了 middleName.length()，IDE 会直接标红提示；

泛型支持：它支持 List<@Nullable String> 这种写法，精确描述集合内部元素的空安全性；

如果在 类级别 或 包级别（package-info.java）加上了 @NullMarked，那包里面没加 @Nullable 的字段就必然不为空；

Projection + Record 场景示例

@NullMarked // 开启“默认非空”模式
public record UserRecord(
    Long id,               // 必须有值，SQL 结果若为 null 则 IDE 报错
    String username,       // 必须有值
    @Nullable String bio   // 数据库里这一列可以为 null
) {}