Spring Boot自定义校验与400错误处理教程

本文旨在解决Spring Boot应用中，使用自定义校验器（如`@ValidList`）时，当校验失败却返回`500 Internal Server Error`而非期望的`400 Bad Request`的问题。通过引入`@RestControllerAdvice`和`@ExceptionHandler`，捕获`ConstraintViolationException`，从而实现统一的异常处理，将校验失败的响应状态码正确映射为`400 Bad Request`，提升API的健壮性和用户体验。

Spring Boot自定义校验与异常处理概述

在构建RESTful API时，数据校验是确保请求有效性和系统稳定性的重要环节。Spring Boot提供了强大的验证框架，结合JSR 303/380（Bean Validation），我们可以轻松地对请求体、路径变量等进行校验。然而，在某些复杂场景下，内置的校验规则可能无法满足需求，这时就需要自定义校验器。

当自定义校验失败时，我们通常期望API返回400 Bad Request状态码，明确告知客户端请求参数不符合规范。然而，如果未正确处理校验失败时抛出的异常，Spring Boot可能会默认返回500 Internal Server Error，这会误导客户端，使其认为服务器内部出现了不可预知的错误，而非简单的请求数据问题。

自定义校验器的实现与潜在问题

考虑一个场景，我们需要校验一个列表，确保它既不为空，也不包含任何空值元素。我们可以通过自定义注解@ValidList及其对应的ListValidator来实现。

自定义校验注解 ValidList：

import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.*;

import static java.lang.annotation.ElementType.*;

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ METHOD, FIELD, CONSTRUCTOR, PARAMETER, TYPE_USE })
@Constraint(validatedBy = ListValidator.class)
public @interface ValidList  {
    String message() default "List cannot empty or contain null values";
    Class[] groups() default {};
    Class[] payload() default {};
}

校验器 ListValidator：

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
import java.util.List;
import java.util.Objects;

public class ListValidator implements ConstraintValidator> {
    @Override
    public boolean isValid(List list,
                           ConstraintValidatorContext context) {
        // 标记列表无效，如果它为空或包含任何空值。
        return !(list == null || list.isEmpty() || list.stream().anyMatch(Objects::isNull));
    }

    @Override
    public void initialize(ValidList constraintAnnotation) {}
}

请求数据模型 Data 和 Entries：

import javax.validation.Valid;
import javax.validation.constraints.NotNull;
import java.util.ArrayList;

@ValidList // 应用自定义校验注解
public class Data extends ArrayList<@Valid Entries> { }

public class Entries {
  @NotNull
  String firstName;

  @NotNull
  String lastName;

  // 构造函数、getter/setter等
}

API控制器 RequestAPI：

import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import javax.validation.Valid;
import javax.validation.constraints.NotNull;

@RestController
public class RequestAPI {
    @PostMapping(value = "/request",
        consumes = MediaType.APPLICATION_JSON_VALUE,
        produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity request(
        @Valid @NotNull @RequestBody(required = false) Data data) {
        // 业务逻辑处理
        return ResponseEntity.ok("Request processed successfully");
    }
}

当客户端发送一个请求，其中Data列表为空、null或包含null元素时，ListValidator的isValid方法将返回false。此时，Spring的校验框架会抛出异常，通常是ConstraintViolationException。如果没有全局的异常处理机制来捕获并处理这类异常，该异常会一直向上抛出，最终被Spring Boot的默认错误处理机制捕获，并以500 Internal Server Error的形式返回给客户端。

解决方案：使用 @RestControllerAdvice 统一处理异常

为了将校验失败的ConstraintViolationException正确地映射为400 Bad Request，我们需要利用Spring框架提供的全局异常处理机制：@RestControllerAdvice结合@ExceptionHandler。

@RestControllerAdvice注解用于定义一个全局的异常处理器，它可以捕获应用中所有控制器抛出的特定类型的异常。@ExceptionHandler则用于指定要处理的异常类型。

实现 ApiExceptionHandler：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

import javax.validation.ConstraintViolationException;

@RestControllerAdvice
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {

    private static final Logger logger = LoggerFactory.getLogger(ApiExceptionHandler.class);

    @ExceptionHandler(value = {ConstraintViolationException.class})
    public ResponseEntity