8 Essential Null‑Handling Rules for Spring Boot 3 to Prevent NPEs

1. Introduction

Improper use of null is a common source of NullPointerException, logical errors and system instability in Java applications. Consistent null‑handling is especially important in Spring Boot 3.x when dealing with collections, Optional, persistence layers and API design.

2. Practical Rules for Null Handling

2.1 Rule 1 – Do not return null from collection‑returning methods

Returning null forces every caller to write defensive checks and creates two possible representations of “no data” (empty list vs null). The recommended practice is to return an empty collection, e.g. Collections.emptyList() or List.of().

public List<Order> findOrdersByUser(Long userId) {
    // Repository already returns an empty list when no rows exist
    return orderRepository.findByUserId(userId);
}

// Caller can iterate safely without null checks
List<Order> orders = service.findOrdersByUser(id);
for (Order order : orders) {
    // ...
}

2.2 Rule 2 – Do not accept null as a valid input unless the contract explicitly permits it

Silently handling null hides upstream bugs and can produce incorrect business results. Use a fail‑fast approach with Objects.requireNonNull (or explicit validation) when null is not part of the method contract.

public BigDecimal applyDiscount(BigDecimal price) {
    Objects.requireNonNull(price, "price must not be null");
    return price.multiply(DISCOUNT);
}

2.3 Rule 3 – Do not use Optional as an entity field

ORM frameworks (e.g. Hibernate) cannot map Optional fields, leading to mapping failures and confusing JSON serialization. Store the raw nullable value in the entity and wrap it in Optional only at the API boundary.

@Entity
public class User {
    // Correct: plain field that may be null
    private String middleName;

    public Optional<String> getMiddleName() {
        return Optional.ofNullable(middleName);
    }
}

2.4 Rule 4 – Never call Optional.get() without protection

Calling get() on an empty Optional throws NoSuchElementException. Prefer orElseThrow() for explicit business exceptions or orElse() / orElseGet() for safe defaults.

// Explicit exception (business logic)
User user = userRepository.findById(id)
    .orElseThrow(() -> new UserNotFoundException(id));

// Safe conversion to DTO with a default value
UserDto dto = userRepository.findById(id)
    .map(UserDto::from)
    .orElse(null);

2.5 Rule 5 – Avoid chained getter calls that can produce null at any step

Expressions such as order.getCustomer().getAddress().getCity() will throw an NPE if any intermediate object is null. Use Optional to safely navigate the object graph and provide a fallback.

String city = Optional.ofNullable(order)
    .map(Order::getCustomer)
    .map(Customer::getAddress)
    .map(Address::getCity)
    .orElse("UNKNOWN");

2.6 Rule 6 – Use a consistent strategy for “missing” values (null vs exception)

Mixing null returns with thrown exceptions forces callers to remember each method’s contract, leading to duplicated defensive code. A typical layered approach is:

Repository layer returns Optional<T> – pure data access, no business logic.

Service layer converts Optional.empty() to a domain‑specific exception.

Controller layer maps the exception to an appropriate HTTP status (e.g., 404).

// Repository
public Optional<User> findByEmail(String email) {
    return Optional.ofNullable(userRepository.find(email));
}

// Service
public User getUserByEmail(String email) {
    return findByEmail(email)
        .orElseThrow(() -> new UserNotFoundException("Email not found: %s".formatted(email)));
}

// Controller
@GetMapping("/users/{email}")
public ResponseEntity<User> getUser(@PathVariable String email) {
    try {
        User user = userService.getUserByEmail(email);
        return ResponseEntity.ok(user);
    } catch (UserNotFoundException e) {
        return ResponseEntity.notFound().build();
    }
}

2.7 Rule 7 – Omit null fields from JSON responses

Serializing null values makes API contracts ambiguous and can confuse front‑end developers. Configure Jackson to exclude nulls either globally or per class.

// Per‑class configuration
@JsonInclude(JsonInclude.Include.NON_NULL)
public class UserDto {
    private String phoneNumber;
}

// Global configuration (application.yml)
spring:
  jackson:
    default-property-inclusion: non_null

2.8 Rule 8 – Prevent database null values from leaking into domain logic

Database null (three‑state) differs from domain boolean logic (two‑state). When a field is logically required, map it to a primitive type; otherwise model the three states explicitly with an enum.

// Two‑state boolean – primitive prevents null
@Column(nullable = false)
private boolean active;

// Three‑state domain – explicit enum
public enum AccountStatus { ACTIVE, INACTIVE, PENDING }

@Column(nullable = false)
@Enumerated(EnumType.STRING)
private AccountStatus status;