Spring Boot 参数校验全局处理(JSR380 + 自定义校验)

<!-- JSR380 参数校验核心依赖（低版本Spring Boot需手动引入） -->
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.2.5.Final</version>
</dependency>
<!-- 可选：validation-api 规范依赖（确保注解识别） -->
<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
</dependency>

// 示例：用户注册参数实体类（所有注解均无导包，直接复制可用）
@Data
public class UserRegisterDTO {
    // 用户名：非空、长度2-20位
    @NotBlank(message = "用户名不能为空")
    @Size(min = 2, max = 20, message = "用户名长度必须在2-20位之间")
    private String username;
    // 密码：非空、长度6-16位
    @NotBlank(message = "密码不能为空")
    @Size(min = 6, max = 16, message = "密码长度必须在6-16位之间")
    private String password;
    // 邮箱：非空、符合邮箱格式
    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;
    // 年龄：非空、18-60岁之间
    @NotNull(message = "年龄不能为空")
    @Min(value = 18, message = "年龄不能小于18岁")
    @Max(value = 60, message = "年龄不能大于60岁")
    private Integer age;
    // 手机号：非空、符合手机号正则（此处用@Pattern临时实现，后续用自定义注解优化）
    @NotBlank(message = "手机号不能为空")
    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
    private String phone;
}

// 示例：用户注册接口（触发参数校验）
@RestController
@RequestMapping("/user")
public class UserController {
    // 注册接口：@Valid 触发UserRegisterDTO的参数校验
    @PostMapping("/register")
    public Result<Void> register(@Valid @RequestBody UserRegisterDTO registerDTO) {
        // 校验通过后，执行注册业务逻辑（无需任何if-else判断参数）
        // 业务逻辑...
        return Result.success("注册成功");
    }
    // 示例：路径参数校验（直接作用于参数上）
    @GetMapping("/{id}")
    public Result<User> getUserById(@PathVariable @NotNull(message = "用户ID不能为空") Long id) {
        // 校验通过，执行查询逻辑
        // 业务逻辑...
        return Result.success(null);
    }
}

// 全局异常处理器：新增参数校验异常捕获（无导包，直接复制可用）
@RestControllerAdvice
public class GlobalExceptionHandler {
    // 统一响应格式（前文已实现，此处复用）
    @Data
    public static class Result<T> {
        private Integer code;
        private String message;
        private T data;
        public static <T> Result<T> success(T data) { /* 实现省略 */ }
        public static <T> Result<T> fail(Integer code, String message) { /* 实现省略 */ }
    }
    // 1. 捕获请求体参数校验失败异常（@RequestBody + @Valid）
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Void> handleMethodArgumentNotValidException(MethodArgumentNotValidException e) {
        // 提取校验失败的第一条提示信息（也可提取所有提示信息，根据需求调整）
        String errorMsg = e.getBindingResult().getFieldErrors().get(0).getDefaultMessage();
        // 返回统一失败响应（状态码400：参数错误）
        return Result.fail(400, errorMsg);
    }
    // 2. 捕获路径参数/请求参数校验失败异常（@PathVariable/@RequestParam + 校验注解）
    @ExceptionHandler(ConstraintViolationException.class)
    public Result<Void> handleConstraintViolationException(ConstraintViolationException e) {
        // 提取校验失败的第一条提示信息
        String errorMsg = e.getConstraintViolations().iterator().next().getMessage();
        // 返回统一失败响应
        return Result.fail(400, errorMsg);
    }
    // 其他异常处理方法（前文已实现，此处省略）
    @ExceptionHandler(Exception.class)
    public Result<Void> handleException(Exception e) { /* 实现省略 */ }
}

// 自定义手机号校验注解（@Phone）
@Target({ElementType.FIELD, ElementType.PARAMETER}) // 注解作用范围：字段、参数
@Retention(RetentionPolicy.RUNTIME) // 保留策略：运行时生效
@Constraint(validatedBy = PhoneValidator.class) // 关联校验器（核心，实现校验逻辑）
public @interface Phone {
    // 校验失败提示信息（默认值，可自定义）
    String message() default "手机号格式不正确";
    // 分组校验（默认分组，可根据需求扩展）
    Class<?>[] groups() default {};
    // 负载（默认，无需修改）
    Class<? extends Payload>[] payload() default {};
}

// 手机号校验器（与@Phone注解关联，实现校验逻辑）
public class PhoneValidator implements ConstraintValidator<Phone, String> {
    // 手机号正则表达式（标准手机号格式：13-19开头，共11位）
    private static final String PHONE_REGEX = "^1[3-9]\\d{9}$";
    /**
     * 初始化方法（可选，用于获取注解中的参数，此处无需使用）
     */
    @Override
    public void initialize(Phone constraintAnnotation) {
        ConstraintValidator.super.initialize(constraintAnnotation);
    }
    /**
     * 核心校验逻辑
     * @param value 待校验的参数（手机号字符串）
     * @param context 校验上下文（无需修改）
     * @return true：校验通过，false：校验失败
     */
    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        // 校验逻辑：非空判断 + 正则匹配
        if (value == null || value.isEmpty()) {
            // 若需要校验手机号非空，可在此处返回false；若允许为空，返回true（结合@NotBlank使用）
            return false;
        }
        // 正则匹配手机号格式
        return value.matches(PHONE_REGEX);
    }
}

// 示例：修改UserRegisterDTO，使用@Phone注解替代@Pattern
@Data
public class UserRegisterDTO {
    // 其他字段不变...

    // 手机号：使用自定义@Phone注解，替代原来的@Pattern，可复用
    @NotBlank(message = "手机号不能为空")
    @Phone(message = "手机号格式不正确（请输入13-19开头的11位手机号）")
    private String phone;
}

// 1. 定义分组接口（空接口，用于区分不同场景）
public interface AddGroup {} // 新增场景分组
public interface UpdateGroup {} // 修改场景分组

// 2. 实体类中指定注解的分组
@Data
public class UserDTO {
    // 新增时校验非空，修改时无需校验（id由前端传入，无需校验）
    @NotNull(message = "用户ID不能为空", groups = AddGroup.class)
    private Long id;

    // 新增和修改时都需要校验非空和长度
    @NotBlank(message = "用户名不能为空", groups = {AddGroup.class, UpdateGroup.class})
    @Size(min = 2, max = 20, message = "用户名长度必须在2-20位之间", groups = {AddGroup.class, UpdateGroup.class})
    private String username;
}

// 3. 接口中指定分组，触发对应分组的校验
@RestController
@RequestMapping("/user")
public class UserController {
    // 新增用户：仅执行AddGroup分组的校验
    @PostMapping("/add")
    public Result<Void> add(@Validated(AddGroup.class) @RequestBody UserDTO userDTO) {
        // 业务逻辑...
        return Result.success();
    }

    // 修改用户：仅执行UpdateGroup分组的校验
    @PutMapping("/update")
    public Result<Void> update(@Validated(UpdateGroup.class) @RequestBody UserDTO userDTO) {
        // 业务逻辑...
        return Result.success();
    }
}