Spring Boot 数据校验 Validation 实战

可以看出上述写法的缺点：代码冗长，不利于维护；每个接口都要写重复的校验逻辑；校验逻辑和业务逻辑耦合，不够优雅。

3. 使用 Validation 的优雅写法

我们可以在实体类上加注解，把校验规则声明在模型上，让 Spring 自动完成校验。

Maven 依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

UserDto 对象加上注解

import javax.validation.constraints.*;

public class UserDto {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 2, max = 10, message = "用户名长度必须在{min}-{max}之间")
    private String username;

    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    // 自带邮箱格式校验，无需自己写正则！
    private String email;

    @NotNull(message = "年龄不能为空")
    @Min(value = 0, message = "年龄最小为{value}")
    @Max(value = 150, message = "年龄最大为{value}")
    private Integer age;

    // 省略 Getter 和 Setter...
}

在 Controller 参数前加@Valid 或@Validated 注解

import javax.validation.Valid;

@RestController
@RequestMapping("/user")
public class UserController {
    @PostMapping("/add")
    // 关键一步：在 @RequestBody 前加上 @Valid 注解
    public String addUser(@Valid @RequestBody UserDto user) {
        // 只需关注核心业务
        System.out.println("用户创建成功：" + user);
        return "success";
    }
}

通过上述使用 validation 改造，Spring 会自动对 UserDto 的字段进行校验，当请求参数不满足规则时，Spring Boot 会自动抛出 MethodArgumentNotValidException 异常，不会进入这个方法体。但我们不能直接给用户返回异常栈，需要统一处理。

4. 全局异常处理（友好返回错误信息）

刚才我们已经说过了参数校验不满足规则，系统会抛出 MethodArgumentNotValidException，那么我们就可以通过 @RestControllerAdvice 捕获 MethodArgumentNotValidException，来实现统一返回错误信息。

import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.util.HashMap;
import java.util.Map;
import java.util.Objects;

@RestControllerAdvice
public class GlobalExceptionHandler {
    /**
     * 处理实体校验异常
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Map<String, Object> handleValidException(MethodArgumentNotValidException e) {
        Map<String, Object> errorResult = new HashMap<>();
        errorResult.put("code", 400);
        errorResult.put("message", "参数校验失败");
        // 从异常对象中拿到具体的错误信息
        // 这里只取第一个错误信息，也可以全部返回
        String defaultMessage = Objects.requireNonNull(e.getBindingResult().getFieldError()).getDefaultMessage();
        errorResult.put("data", defaultMessage);
        return errorResult;
    }
}

最后我们可以使用 Postman 或 curl 测试，观察接口返回的 JSON 异常数据。

5. 常用校验注解

6. 分组校验

当同一个实体类在不同场景下有不同的校验规则时，比如新增时 ID 应为空，而更新时 ID 不能为空，这时就需要分组校验。

定义分组接口（标记接口）

public interface CreateGroup {}
// 创建分组
public interface UpdateGroup {}
// 更新分组

在实体上指定分组

继续改造一下我们的 UserDto，这时候需要增加 id 字段。

public class UserDto {
    @Null(groups = CreateGroup.class, message = "创建时 ID 必须为空")
    @NotNull(groups = UpdateGroup.class, message = "更新时 ID 不能为空")
    private Long id;

    @NotBlank(message = "用户名不能为空", groups = {CreateGroup.class, UpdateGroup.class})
    private String username;

    // ... 其他字段
}

在 Controller 中使用@Validated 指定分组

@PostMapping("/create")
public String create(@Validated(CreateGroup.class) @RequestBody UserDto user) {
    // ... 创建逻辑
}

@PostMapping("/update")
public String update(@Validated(UpdateGroup.class) @RequestBody UserDto user) {
    // ... 更新逻辑
}

7. 结语

通过使用 Spring Boot Validation，我们可以告别繁琐的手动参数校验，让代码更加简洁、优雅、易维护。希望本文能帮助你在项目中更好地应用数据校验机制，提升开发效率和代码质量，是开发中必不可少的利器！