How Spring Boot 4’s JSpecify Eliminates NullPointerExceptions

Problem: NullPointerExceptions in production

NullPointerException (NPE) is a long‑standing "ghost" for Java developers. Code that runs fine locally can suddenly throw an NPE in production because the traditional Java type system cannot distinguish nullable from non‑null types at compile time.

JSpecify – compile‑time null checking

JSpecify is a modern Java null‑safety annotation specification. Its core idea is to let the type system carry nullability information and verify it during compilation.

Spring Boot 4 new feature: default non‑null

Spring Boot 4 replaces the old JSR‑305 annotation set with JSpecify, moving null‑safety checks from runtime discovery to compile‑time prevention. The framework introduces a default non‑null policy: unless a value is explicitly marked with @Nullable, it is considered non‑null.

Code comparison before and after

// Spring Boot 4 之前 - 返回值是否可空？无从知晓！
@Service
public class PigUserService {
    public PigUser findUserByUsername(String username) {
        return pigUserRepository.findByUsername(username); // 可能返回 null
    }
}

// Spring Boot 4 使用 JSpecify - 显式标注可空性
@Service
@NullMarked // 默认所有类型为非空
public class PigUserService {
    @Nullable
    public PigUser findUserByUsername(String username) {
        return pigUserRepository.findByUsername(username); // 明确表示可能返回 null
    }
}

Practical example: Pig Mall order service

The following service shows how @NullMarked guarantees non‑null parameters while @Nullable marks optional ones.

@NullMarked
package com.pig4cloud.pigx.mall.order;

@Service
public class PigOrderService {
    public PigOrder createOrder(String username, @Nullable String couponCode) {
        // username 保证非空 - 无需检查！
        sendConfirmation(username);

        // couponCode 可能为空 - 必须进行检查
        if (couponCode != null) {
            applyCoupon(couponCode);
        }
        return new PigOrder(username, couponCode);
    }
}

Null‑safety for collection types

JSpecify also supports nullable elements inside collections. The example returns a list that itself is non‑null but may contain null entries.

@Service
public class PigReviewService {
    // 列表本身非空，但可以包含空元素
    public List<@Nullable String> getProductReviews() {
        List<@Nullable String> reviews = new ArrayList<>();
        reviews.add("商品质量很好");           // 评价 1：已填写
        reviews.add(null);                    // 评价 2：留空
        reviews.add("lengleng 的服务态度非常棒"); // 评价 3：已填写
        return reviews;
    }

    public int calculateReviewRate(List<@Nullable String> reviews) {
        long completed = reviews.stream()
                .filter(Objects::nonNull)
                .count();
        return (int) ((completed * 100) / reviews.size());
    }
}

Project configuration steps

Step 1: Set package‑level default rule

@NullMarked
package com.pig4cloud.pigx.admin.service;

import org.jspecify.annotations.NullMarked;

Important: @NullMarked only applies to the package where the file resides; you need a separate package-info.java for each package that should use the default‑non‑null rule.

Step 2: Annotate nullable return values

@NullMarked
@Service
public class PigGoodsService {
    @Nullable
    public PigGoods findById(Long id) {
        return goodsRepository.findById(id).orElse(null);
    }

    // 更佳实践：新 API 使用 Optional
    public Optional<PigGoods> findGoodsById(Long id) {
        return goodsRepository.findById(id);
    }
}

Step 3: Handle nullable parameters

@RestController
@NullMarked
public class PigGoodsController {
    @PostMapping("/goods")
    public PigGoods createGoods(
            @RequestBody PigGoods goods,
            @RequestHeader("X-User-Id") @Nullable String userId) {

        // goods 保证非空 - 无需检查！
        validateGoods(goods);

        // userId 可能为空
        if (userId != null) {
            auditLog(userId, "创建商品: " + goods.getName());
        }
        return pigGoodsService.save(goods);
    }
}

Compile‑time safety with NullAway

Integrating NullAway turns potential NPEs into build failures. The Maven configuration below adds NullAway as an annotation processor and limits its checks to code annotated with @NullMarked.

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.14.0</version>
      <configuration>
        <release>17</release>
        <encoding>UTF-8</encoding>
        <fork>true</fork>
        <compilerArgs>
          <arg>-XDcompilePolicy=simple</arg>
          <arg>--should-stop=ifError=FLOW</arg>
          <arg>-Xplugin:ErrorProne -Xep:NullAway:ERROR -XepOpt:NullAway:OnlyNullMarked</arg>
          <!-- add‑exports arguments omitted for brevity -->
        </compilerArgs>
        <annotationProcessorPaths>
          <path>
            <groupId>com.google.errorprone</groupId>
            <artifactId>error_prone_core</artifactId>
            <version>2.38.0</version>
          </path>
          <path>
            <groupId>com.uber.nullaway</groupId>
            <artifactId>nullaway</artifactId>
            <version>0.12.7</version>
          </path>
        </annotationProcessorPaths>
      </configuration>
    </plugin>
  </plugins>
</build>

With NullAway enabled, the following controller fails to compile because it dereferences a @Nullable value without a null check.

@NullMarked
public class PigOrderController {
    @GetMapping("/orders/{username}")
    public String getOrderStatus(@PathVariable String username) {
        PigOrder order = pigOrderService.findByUsername(username); // 返回 @Nullable

        // ❌ 编译错误！"解引用表达式 order 为 @Nullable"
        return order.getStatus();

        // ✅ 必须处理空值情况
        // return order != null ? order.getStatus() : "未找到订单";
    }
}

Why choose @Nullable over Optional?

Although Java 8 provides Optional<T>, the author argues that @Nullable has distinct advantages.

API compatibility : Changing a method to return Optional breaks existing callers, while adding @Nullable merely makes the nullability explicit without breaking code.

Runtime overhead : Each Optional allocation adds object‑creation cost, which can accumulate in performance‑critical paths. @Nullable is compile‑time metadata with no runtime cost.

Usage scope limited : The JDK documentation advises Optional only as a return type; using it for parameters or fields leads to awkward APIs. @Nullable works naturally on parameters and fields.

Comparison of typical usage:

// Using Optional
return pigUserService.findUser(id)
    .map(PigUser::getName)
    .orElse("未知用户");

// Using @Nullable
PigUser user = pigUserService.findUser(id);
return user != null ? user.getName() : "未知用户";

Conclusion

When you see @NullMarked and @Nullable in Spring Boot 4 code, they are not mysterious annotations but the framework’s adoption of modern Java null‑safety practices. By expressing "which values may be null" in the type system and combining it with static analysis tools like NullAway, potential NPEs are caught at compile time, improving code reliability and maintainability.