Spring Boot Validation 声明式参数校验

Lyyaoo.2026-08-21 23:40

文章目录

前言
基本使用
常见校验注解
分组校验

前言

Spring Boot Validation 是一套基于 Jakarta Bean Validation（原 JSR 303/380）规范的数据校验框架。它的核心作用就是帮你自动检查接口传入的参数是否合法，避免你在业务代码里写一堆 if (xxx == null) { return "参数错误"; } 这样的重复代码。

基本使用

在实体类字段上加注解（定义规则）在接收参数的 Java Bean 里，用注解声明每个字段的约束条件。

java 复制代码

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

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

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

在 Controller 接口参数上加 @Valid（触发校验），在接收参数的位置标记 @Valid，Spring 就会在校验失败时自动抛出异常。

java 复制代码

@PostMapping("/user")
public R addUser(@Valid @RequestBody UserDTO user) {
    // 如果校验不通过，根本不会执行到这行代码
    return R.ok();
}

常见校验注解

注解	作用
@NotNull	不能为 null（任何类型）
@NotBlank	不能为 null，且去除空格后长度必须大于0（专用于字符串）
@NotEmpty	不能为 null，且集合/数组/字符串长度必须大于0
@Size(min, max)	限制长度范围（字符串、集合、数组）
@Min / @Max	限制数字大小
@Email	检查是否符合邮箱格式
@Pattern(regexp)	用正则表达式校验

分组校验

有时候，同一个实体类在新增和修改时的校验规则不一样（比如新增时 ID 必须为空，修改时 ID 必须不为空）。这时可以用分组（Groups）：

java 复制代码

// 定义两个空接口作为分组标识
public interface AddGroup {}
public interface UpdateGroup {}

// 实体类里指定分组
public class UserDTO {
    @NotNull(message = "ID不能为空", groups = {UpdateGroup.class})
    @Null(message = "ID必须为空", groups = {AddGroup.class})
    private Long id;
}

// 接口使用时指定分组
@PostMapping("/add")
public R add(@Validated(AddGroup.class) @RequestBody UserDTO user) { ... }

@PutMapping("/update")
public R update(@Validated(UpdateGroup.class) @RequestBody UserDTO user) { ... }

注意：普通 @Valid 不支持分组，要用 @Validated（Spring 提供的扩展注解）来代替。