Spring Boot 3.2中@RequestBody接收空JSON字符串导致NullPointerException的根因与解决方案

qq_54337203

398人浏览 · 2026-03-15 09:59:10

qq_54337203 · 2026-03-15 09:59:10 发布

Spring Boot 3.2中@RequestBody接收空JSON字符串导致NullPointerException的根因与解决方案

适用环境：Spring Boot 3.2.4 + Spring Framework 6.1.6 + Jackson 2.15.2 + Java 17+

🔍 问题场景

当客户端发送空JSON对象 "{}" 到 @PostMapping 接口时，若DTO字段未设默认值且无显式空值处理逻辑，Spring MVC 可能抛出 NullPointerException，而非预期的 HttpMessageNotReadableException 或 400 错误——这在微服务间契约调用、前端表单重置等场景高频发生。

@PostMapping("/user")
public ResponseEntity<String> createUser(@RequestBody UserDTO user) {
    return ResponseEntity.ok(user.getName().toUpperCase()); // ← NPE here if user.getName() == null
}

🧨 复现代码

// UserDTO.java
public class UserDTO {
    private String name; // 无默认值，无@NonNull，无@JsonSetter(defaultValue = "")
    private Integer age;
    // getter/setter...
}

请求体：{} → user.getName() 为 null → toUpperCase() 触发 NPE。

⚙️ 根因分析：Jackson + Spring MVC 协同机制

关键链路：

HttpMessageConverter → MappingJackson2HttpMessageConverter 
  → Jackson's ObjectMapper.readValue("{}", UserDTO.class) 
    → 构造UserDTO实例，所有字段初始化为null 
      → Spring不校验@RequestBody对象非空性 → 直接注入Controller方法

⚠️ 注意：这不是Spring Boot Bug，而是Jackson反序列化语义与Spring参数解析器（AbstractMessageConverterMethodArgumentResolver）默认行为的组合结果。

✅ 三种工业级解决方案

方案1：使用 `@JsonSetter(nulls = Nulls.SKIP)`（推荐）

适用于字段级精细控制，避免污染业务逻辑：

public class UserDTO {
    @JsonSetter(nulls = Nulls.SKIP)
    private String name;
    @JsonSetter(nulls = Nulls.AS_EMPTY)
    private List<String> tags = new ArrayList<>();
}

✅ 优势：语义清晰、零侵入Controller、兼容JDK 17+；
❌ 注意：需Jackson 2.12+，且不解决name.toUpperCase()处NPE，需配合Objects.requireNonNull或Optional。

方案2：DTO字段声明为 `@Nullable` + 全局`@Valid`校验

public class UserDTO {
    @NotBlank(message = "姓名不能为空")
    @Nullable
    private String name;
}

@PostMapping("/user")
public ResponseEntity<String> createUser(@Valid @RequestBody UserDTO user) { ... }

需启用：spring.mvc.throw-exception-if-no-handler-found=true + 自定义GlobalExceptionHandler捕获MethodArgumentNotValidException。

方案3：全局`HandlerExceptionResolver`兜底（防御性编程）

@ControllerAdvice
public class NullSafetyExceptionHandler {
    @ExceptionHandler(NullPointerException.class)
    public ResponseEntity<Object> handleNPE(HttpServletRequest req, NullPointerException e) {
        if (req.getRequestURI().contains("/api/")) {
            return ResponseEntity.badRequest()
                .body(Map.of("error", "Invalid request body: null field detected"));
        }
        throw e;
    }
}

⚠️ 安全警示：切勿在生产环境禁用Jackson的DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES或全局设置@JsonInclude(JsonInclude.Include.NON_NULL)替代字段级策略——这会掩盖真实数据缺失问题，违反可观测性原则。

📊 方案对比表

方案	侵入性	可测试性	是否阻断NPE	推荐场景
`@JsonSetter`	低（仅DTO）	高（单元测试覆盖）	否（需额外判空）	字段语义明确、需兼容旧客户端
`@Valid` + `@NotBlank`	中（需改DTO+Controller）	最高（Bean Validation TCK）	是（400提前拦截）	新建接口、强契约要求
全局NPE Handler	高（跨域影响）	中（需Mock HTTP）	是（运行时兜底）	遗留系统快速加固