Spring Boot 中处理无效 JSON 请求的完整实践指南-java教程-PHP中文网

Spring Boot 中处理无效 JSON 请求的完整实践指南

本文介绍如何在 Spring Boot 中优雅处理控制器层的无效 JSON 输入，包括使用 @Valid 校验、@NotNull 等注解约束字段、添加空值防护逻辑，并通过 @ControllerAdvice 统一返回结构化错误响应。

本文介绍如何在 spring boot 中优雅处理控制器层的无效 json 输入，包括使用 `@valid` 校验、`@notnull` 等注解约束字段、添加空值防护逻辑，并通过 `@controlleradvice` 统一返回结构化错误响应。

在 Spring Boot 应用中，当客户端提交格式正确但语义非法的 JSON（如缺失必需字段、字段名拼写错误），Jackson 仍会成功反序列化出一个部分为空属性的对象（例如 name == null），导致后续业务逻辑（如 ship.getName().equals(...)）抛出 NullPointerException。这不仅暴露了内部实现细节，也违背了 REST API 的契约原则——应尽早拦截并明确告知客户端输入错误，而非让服务层崩溃。

✅ 正确做法：分层防御 + 声明式校验

1. 引入校验依赖

确保 pom.xml 中包含 Spring Validation 支持（Spring Boot 3.x 默认已内置，无需显式指定版本）：

<dependency><groupid>org.springframework.boot</groupid><artifactid>spring-boot-starter-validation</artifactid></dependency>

2. 在 DTO 中声明约束规则

为 Ship 类添加字段级校验注解，明确语义要求。注意：@JsonProperty("Name") 与 Java 字段名无关，校验作用于反序列化后的对象属性：

public class Ship implements Serializable {
    @NotNull(message = "The name is mandatory")
    @JsonProperty("Name")
    private String name;

    @JsonProperty("Owner")
    private String owner;

    // 必须保留无参构造器（Jackson 反序列化所需）
    public Ship() {}

    public Ship(String name, String owner) {
        this.name = name;
        this.owner = owner;
    }

    // getter/setter（略）
}

⚠️ 关键点：@NotNull 仅在校验触发时生效；若未在 @RequestBody 上加 @Valid，该注解将被完全忽略。

3. 控制器启用校验

在方法参数上添加 @Valid，使 Spring 在绑定 JSON 后自动执行约束检查：

@PostMapping(value = "/shipdetails")
public ResponseEntity<void> acceptShip(@Valid @RequestBody Ship ship, HttpServletRequest request) {
    shipService.checkShip(ship);
    return ResponseEntity.ok().build();
}</void>

此时，若请求体中缺失 "Name" 字段（或传入 null），Spring 将在进入控制器方法前抛出 MethodArgumentNotValidException，业务逻辑 checkShip() 不会被调用。

dmap-jsapi-skill

DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。

下载

4. 增强服务层健壮性（兜底防护）

尽管校验前置，仍建议在 checkShip() 中加入空值判断，避免未来绕过校验路径时引发 NPE：

@Service
public class ShipService {
    public Boolean checkShip(Ship ship) {
        // 显式判空，兼顾可读性与安全性
        if (ship != null && StringUtils.isNotBlank(ship.getName()) 
            && "Queen Mary".equals(ship.getName())) { // 推荐常量在前，避免 NPE
            // do something
        }
        return false;
    }
}

? 提示：使用 "Queen Mary".equals(ship.getName()) 替代 ship.getName().equals("Queen Mary") 是防御性编程最佳实践。

5. 全局异常处理：返回友好 JSON 错误

默认的 MethodArgumentNotValidException 响应包含冗长堆栈，不符合生产环境 API 规范。通过 @ControllerAdvice 统一捕获并格式化：

@ControllerAdvice
public class ValidationExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<map string>> handleValidationErrors(
            MethodArgumentNotValidException ex) {

        Map<string string> errors = ex.getBindingResult()
                .getFieldErrors()
                .stream()
                .collect(Collectors.toMap(
                        FieldError::getField,
                        FieldError::getDefaultMessage,
                        (a, b) -> a, // 冲突时保留第一个
                        LinkedHashMap::new
                ));
        return ResponseEntity.badRequest().body(errors);
    }
}</string></map>

✅ 效果：对无效 JSON（如 { "name_wrong":"test", "owner":"Lloyds" }）返回清晰、简洁、机器可解析的响应：