Spring Boot API端点Builder模式问题：Optional字段空指针异常

你的问题核心是Jackson反序列化时没有正确通过Builder初始化Optional字段，导致priority最终为null，而非预期的Optional.empty()。以下是具体的排查和修复方案：

1. 修正Builder的初始化逻辑 #

首先检查你的Builder类，必须给Optional类型的字段默认赋值为Optional.empty()，而不是让它保持null状态。如果之前的Builder中priority没有默认初始化，当API请求不包含该字段时，Jackson可能不会调用对应的setter方法，导致字段留空为null。

示例修正后的Builder：

public static class Builder {
    // 必填字段必须在Builder构造方法中传入
    private final String requiredField;
    // 可选字段默认初始化为Optional.empty()
    private Optional<Integer> priority = Optional.empty();

    public Builder(String requiredField) {
        this.requiredField = requiredField;
    }

    // 处理传入Optional的情况，同时防御null参数
    public Builder priority(Optional<Integer> priority) {
        this.priority = priority != null ? priority : Optional.empty();
        return this;
    }

    // 可选：重载接受Integer的方法，方便调用方直接传值（包括null）
    public Builder priority(Integer priority) {
        this.priority = Optional.ofNullable(priority);
        return this;
    }

    public ConfigRequestModel build() {
        return new ConfigRequestModel(this);
    }
}

同时，在模型类的构造方法中，再次防御Builder中可能的null值：

private ConfigRequestModel(Builder builder) {
    this.requiredField = builder.requiredField;
    // 双重保险，确保不会出现null
    this.priority = builder.priority != null ? builder.priority : Optional.empty();
}

2. 强制Jackson使用Builder进行反序列化 #

Jackson默认可能不会自动识别你的Builder类，尤其是当模型类存在其他构造方法时。需要通过注解明确指定反序列化使用的Builder：

• 在模型类上添加@JsonDeserialize(builder = ConfigRequestModel.Builder.class)
• 在Builder类上添加@JsonPOJOBuilder(withPrefix = "")（如果你的Builder方法是priority(...)而非setPriority(...)，如果是带set前缀的，把withPrefix设为"set"）

示例完整模型类：

import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import com.fasterxml.jackson.databind.annotation.JsonPOJOBuilder;
import java.util.Optional;

@JsonDeserialize(builder = ConfigRequestModel.Builder.class)
public class ConfigRequestModel {
    private final String requiredField;
    private final Optional<Integer> priority;

    private ConfigRequestModel(Builder builder) {
        this.requiredField = builder.requiredField;
        this.priority = builder.priority != null ? builder.priority : Optional.empty();
    }

    public String getRequiredField() {
        return requiredField;
    }

    public Optional<Integer> getPriority() {
        return priority;
    }

    @JsonPOJOBuilder(withPrefix = "")
    public static class Builder {
        private final String requiredField;
        private Optional<Integer> priority = Optional.empty();

        public Builder(String requiredField) {
            this.requiredField = requiredField;
        }

        public Builder priority(Optional<Integer> priority) {
            this.priority = priority != null ? priority : Optional.empty();
            return this;
        }

        public Builder priority(Integer priority) {
            this.priority = Optional.ofNullable(priority);
            return this;
        }

        public ConfigRequestModel build() {
            return new ConfigRequestModel(this);
        }
    }
}

3. 确认Jackson对Optional的支持 #

Spring Boot的spring-boot-starter-web依赖已经包含jackson-datatype-jdk8模块（专门处理JDK8+的Optional、LocalDateTime等类型），如果是自定义依赖，确保已引入该模块：

<!-- Maven示例 -->
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jdk8</artifactId>
</dependency>

4. 验证反序列化场景 #

• 当API请求中不包含priority字段时，Jackson会使用Builder的默认值Optional.empty()
• 当请求中传入priority: null时，通过重载的priority(Integer)方法会转为Optional.empty()
• 当请求中传入priority: 5时，会转为Optional.of(5)

此时调用configRequestModel.getPriority().isEmpty()就不会再抛出NullPointerException了。

内容的提问来源于stack exchange，提问作者Al3x4ndru1