基于Spring Validation实现全局参数校验异常处理的示例详解

<!-- Spring Validation 核心依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<!-- Web依赖（若项目已引入可忽略） -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

import jakarta.validation.constraints.*; // Spring Boot 3.x使用jakarta包，2.x为javax包

public class UserDTO {
    // 主键非空
    @NotNull(message = "用户ID不能为空")
    private Long id;

    // 用户名非空且长度1-20
    @NotBlank(message = "用户名不能为空")
    @Size(min = 1, max = 20, message = "用户名长度需在1-20字符之间")
    private String username;

    // 年龄18-60岁
    @Min(value = 18, message = "年龄不能小于18岁")
    @Max(value = 60, message = "年龄不能大于60岁")
    private Integer age;

    // 邮箱格式合法
    @Email(message = "邮箱格式不正确")
    private String email;

    // getter/setter省略
}

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import jakarta.validation.Valid;

@RestController
public class UserController {
    // 新增用户接口，@Valid触发UserDTO的校验
    @PostMapping("/user/add")
    public String addUser(@Valid @RequestBody UserDTO userDTO) {
        // 校验通过后执行业务逻辑
        return "用户新增成功：" + userDTO.getUsername();
    }
}

import lombok.AllArgsConstructor;
import lombok.Data;

@Data
@AllArgsConstructor
public class Result<T> {
    // 状态码：200成功，400参数错误，500系统错误
    private Integer code;
    // 提示信息
    private String message;
    // 响应数据（成功时返回，失败时为null）
    private T data;

    // 静态工厂方法：参数错误响应
    public static Result<Void> paramError(String message) {
        return new Result<>(400, message, null);
    }

    // 静态工厂方法：成功响应（可省略）
    public static <T> Result<T> success(T data) {
        return new Result<>(200, "success", data);
    }
}

import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import jakarta.validation.ConstraintViolation;
import jakarta.validation.ConstraintViolationException;
import java.util.stream.Collectors;

// 全局异常处理，作用于所有@RestController
@RestControllerAdvice
public class GlobalValidationExceptionHandler {

    /**
     * 处理请求体参数校验失败（@RequestBody + @Valid）
     * 异常类型：MethodArgumentNotValidException
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Void> handleMethodArgumentNotValid(MethodArgumentNotValidException e) {
        // 提取所有字段的错误信息（如多个参数校验失败，合并提示）
        String errorMsg = e.getBindingResult().getFieldErrors().stream()
                .map(FieldError::getDefaultMessage) // 获取每个字段的自定义错误信息
                .collect(Collectors.joining("；")); // 用“；”分隔多个错误

        // 返回参数错误响应
        return Result.paramError(errorMsg);
    }

    /**
     * 处理路径参数/请求参数校验失败（如@RequestParam/@PathVariable）
     * 异常类型：ConstraintViolationException
     */
    @ExceptionHandler(ConstraintViolationException.class)
    public Result<Void> handleConstraintViolation(ConstraintViolationException e) {
        // 提取参数错误信息
        String errorMsg = e.getConstraintViolations().stream()
                .map(ConstraintViolation::getMessage)
                .collect(Collectors.joining("；"));

        return Result.paramError(errorMsg);
    }
}

{
  "id": 1,
  "username": "",
  "age": 17,
  "email": "invalid-email"
}

{
  "code": 400,
  "message": "用户名不能为空；年龄不能小于18岁；邮箱格式不正确",
  "data": null
}

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import jakarta.validation.constraints.Min;

@GetMapping("/user/{userId}")
public String getUser(@Min(value = 1, message = "用户ID不能小于1") @PathVariable Long userId) {
    return "查询用户ID：" + userId;
}

{
  "code": 400,
  "message": "用户ID不能小于1",
  "data": null
}