使用spring-boot-starter-validation进行参数校验

一、maven 依赖

对于 Spring Boot 2.x :

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

对于 Spring Boot 3.x（Jakarta 包名）:
依赖不变，但代码里引用的包名发生变化：javax.validation.* → jakarta.validation.*

如果没引入这个依赖：@Valid 不生效，校验注解写了等于没写

二、全局异常处理

全局异常处理用于参数校验失败以及业务异常时，将接口错误信息返回

1.定义通用返回类

publicclassApiResult<T>{privateintcode;privateStringmessage;privateTdata;publicstatic<T>ApiResult<T>fail(Stringmessage,Tdata){returnnewApiResult<>(400,message,data);}publicApiResult(){}publicApiResult(intcode,Stringmessage,Tdata){this.code=code;this.message=message;this.data=data;}publicintgetCode(){returncode;}publicvoidsetCode(intcode){this.code=code;}publicStringgetMessage(){returnmessage;}publicvoidsetMessage(Stringmessage){this.message=message;}publicTgetData(){returndata;}publicvoidsetData(Tdata){this.data=data;}}

2.全局异常处理类

importorg.springframework.web.bind.MethodArgumentNotValidException;importorg.springframework.web.bind.annotation.ExceptionHandler;importorg.springframework.web.bind.annotation.RestControllerAdvice;importjavax.validation.ConstraintViolationException;importjava.util.HashMap;importjava.util.List;importjava.util.Map;importjava.util.stream.Collectors;@RestControllerAdvicepublicclassGlobalExceptionHandler{/** RequestBody 校验失败 **/@ExceptionHandler(MethodArgumentNotValidException.class)publicApiResult<List<Map<String,String>>>handleMethodArgumentNotValid(MethodArgumentNotValidExceptionex){List<Map<String,String>>errors=ex.getBindingResult().getFieldErrors().stream().map(e->{Map<String,String>m=newHashMap<>();m.put("field",e.getField());m.put("message",e.getDefaultMessage());returnm;}).collect(Collectors.toList());returnApiResult.fail("参数校验失败",errors);}/** RequestParam / PathVariable 校验失败 **/@ExceptionHandler(ConstraintViolationException.class)publicApiResult<List<Map<String,String>>>handleConstraintViolation(ConstraintViolationExceptionex){List<Map<String,String>>errors=ex.getConstraintViolations().stream().map(v->{Map<String,String>m=newHashMap<>();// propertyPath 形如：get.id / method.arg0m.put("field",v.getPropertyPath().toString());m.put("message",v.getMessage());returnm;}).collect(Collectors.toList());returnApiResult.fail("参数校验失败",errors);}}

三、@Valid / @Validated

1.@Valid（最常用）

importjakarta.validation.Valid;

作用：触发校验，本身不定义规则
常见位置：Controller 方法参数、成员变量（级联校验）

示例：

@PostMapping("/add")publicvoidadd(@RequestBody@ValidUserDTOdto){}

没有 @Valid，UserDTO 里的所有校验注解都不会执行

2.@Validated（Spring 提供，增强版）

importorg.springframework.validation.annotation.Validated;

特点：支持分组校验，可用在 类、方法上

示例：

@Validated@RestControllerpublicclassUserController{}

90% 场景用 @Valid 即可

四、常见校验注解

1. @NotNull（最基础）

含义：

• 不能为 null

• 可以是空字符串 “”

适用类型：

• 所有对象类型（Integer、Long、String、List…）

@NotNull(message="用户ID不能为空")privateLonguserId;

2. @NotEmpty（比 NotNull 严格一点）

含义：

• 不能为 null

• 不能为 “”

• 集合不能是空集合

适用类型：

• String

• Collection / Map / Array

@NotEmptyprivateStringname;@NotEmptyprivateList<String>roles;

3. @NotBlank（字符串专用，最常用）

含义：

• 不能为 null

• 不能为 “”

• 不能是 " "（空白）

适用类型：

• 适用于 String

@NotBlank(message="用户名不能为空")privateStringusername;

4. @Length（字符串长度，Hibernate 扩展）

适用类型：

• 只能用于 String

importorg.hibernate.validator.constraints.Length;@Length(min=6,max=20,message="长度必须在6-20位之间")privateStringpassword;

5. @Size（通用长度校验）

@Size(min=1,max=5)privateList<Long>ids;

适用类型：

• String

• Collection

• Map

• Array

与 @Length 区别：

注解 适用范围
@Length : String（Hibernate）
@Size : String + 集合（标准）

6. @Min / @Max（数值范围）

@Min(1)@Max(100)privateIntegerage;

⚠️ 不能校验字符串

7. @Positive / @PositiveOrZero（推荐）

@Positive// > 0@PositiveOrZero// >= 0

@PositiveprivateLongamount;

8. @Email（邮箱校验）

@Email(message="邮箱格式不正确")privateStringemail;

9. @Pattern（正则校验，强力）

@Pattern(regexp="^1[3-9]\\d{9}$",message="手机号格式错误")privateStringphone;

10. @AssertTrue / @AssertFalse

@AssertTrueprivateBooleanagree;

五、测试

importorg.hibernate.validator.constraints.Length;importjavax.validation.Valid;importjavax.validation.constraints.Email;importjavax.validation.constraints.Min;importjavax.validation.constraints.NotBlank;importjavax.validation.constraints.NotEmpty;importjavax.validation.constraints.NotNull;importjavax.validation.constraints.Positive;importjava.util.List;publicclassStudent{@NotBlank(message="用户名不能为空")privateStringname;@NotBlank(message="stuendId不能为空")@Length(min=6,max=20,message="stuendId长度必须在6-20位之间")privateStringstuendId;@NotNull(message="teacherName不能为null")privateStringteacherName;@Min(value=18,message="年龄必须大于18岁")privateIntegerage;@Email(message="邮箱格式不正确")privateStringemail;@Positive(message="amount要大于0")privateLongamount;@NotEmpty(message="roles不能为空")privateList<String>roles;/** 级联校验：如果要校验这个列表里的 Address 对象，必须加 @Valid **/@NotNull(message="地址列表不能为空")@ValidprivateList<SendMessageModel>addresses;//省略get、set 方法}

importorg.hibernate.validator.constraints.Length;importjavax.validation.constraints.NotBlank;publicclassSendMessageModel{@NotBlank(message="mobile不能为空")Stringmobile;@Length(min=6,max=20,message="sign长度必须在6-20位之间")Stringsign;@NotBlank(message="content不能为空")Stringcontent;//省略get、set 方法}

1.post 接口

importcom.xiaohaitang.somedemo.exception.Student;importorg.springframework.web.bind.annotation.*;importjavax.validation.Valid;@RestController@RequestMapping(value="/apiList")publicclassUsercontroller{@PostMapping(value="/v1/addStudents")publicStringvalidChechaAddStudents(@RequestBody@ValidStudentstudent){return"success";}}

入参：

{"age":0,"email":"string","amount":0,"addresses":[{}]}

响应：

{"code":400,"message":"参数校验失败","data":[{"field":"teacherName","message":"teacherName不能为null"},{"field":"email","message":"邮箱格式不正确"},{"field":"addresses[0].mobile","message":"mobile不能为空"},{"field":"amount","message":"amount要大于0"},{"field":"age","message":"年龄必须大于18岁"},{"field":"name","message":"用户名不能为空"},{"field":"addresses[0].content","message":"content不能为空"},{"field":"stuendId","message":"stuendId不能为空"},{"field":"roles","message":"roles不能为空"}]}

2.get 请求

必须在类上增加@Validated参数里的校验才会生效

importorg.hibernate.validator.constraints.Length;importorg.springframework.validation.annotation.Validated;importorg.springframework.web.bind.annotation.*;importjavax.validation.constraints.NotBlank;importjavax.validation.constraints.NotNull;importjavax.validation.constraints.Positive;@Validated// 必须：启用方法参数校验@RestController@RequestMapping(value="/apiList")publicclassUsercontroller{@GetMapping("/test")publicStringtest(@RequestParam@NotBlank(message="name 不能为空")@Length(min=6,max=20,message="name长度必须在6-20位之间")Stringname,@RequestParam@NotNull(message="id 不能为空")@Positive(message="id 必须大于 0")Longid){return"success";}}

入参：

http://localhost:8080/apiList/test?id=0&name=aaa

响应：

{"code":400,"message":"参数校验失败","data":[{"field":"test.id","message":"id 必须大于 0"},{"field":"test.name","message":"name长度必须在6-20位之间"}]}