SpringBoot使用注解校验参数

文章目录

  • 内置注解参数校验
    • 引入依赖
    • 常用注解
    • 使用方式
    • @Validated和@Valid
    • 嵌套校验
  • 自定义注解参数校验
    • 编写自定义注解
    • 实现注解校验类
    • 使用自定义注解
    • 自定义注解属性
  • 分组校验
    • 定义分组接口
    • 校验参数注解上指定分组类
    • Controller层添加@Validated注解并指定分组类

内置注解参数校验

引入依赖

springboot 2.3之前的版本只需要引入web,之后的版本还需要引入validation组件。

<dependency>
    <groupId>org.springframework.bootgroupId>
    <artifactId>spring-boot-starter-webartifactId>
dependency>
<dependency>
    <groupId>org.springframework.bootgroupId>
    <artifactId>spring-boot-starter-validationartifactId>
dependency>

常用注解

注解 说明
@AssertFalse 值必须为false或null
@AssertTrue 值必须为true或null
@DecimalMax 必须为数字,且不能超过指定的最大值
@DecimalMin 必须为数字,且不能小于指定的最小值
@Digits 必须为数字,且位数必须在指定范围内
@Email 值必须符合email格式
@Max 必须不大于指定的最大值
@Min 必须不小于指定的最小值
@NotNull 值不能为null
@NotBlank 只适用于字符串,值不能为null,且字符串使用trim()后也不能为空
@NotEmpty 值不能为null,字符串不能为空,数组、集合、map等大小不能为0
@Pattern 值必须满足指定的正则表达式
@Positive 值必须为正整数
@Size 元素大小必须在指定范围内

使用方式

校验的注解有@Validated或@Valid,常见的校验的场景有以下两种:

  • 校验实体结构中的字段

    @Data
    public class User {
    
        @NotEmpty(message = "user name cannot be null or empty.")
        private String name;
    
        @Positive(message = "user age must larger than zero.")
        private int age;
    
        @Email(message = "email format must be correct.")
        private String email;
    }
    
  • 在Controller层直接校验请求参数

    @GetMapping("/demo/users/{name}")
    public User getUserByName(@PathVariable(value = "name") 
                              @Size(min = 1, max = 20)  String name) {
        return userService.getUserByName(name);
    }
    

要使得上述注解生效,只需要在Controller层做如下处理:

  • 对于实体类User的校验,可以直接在Controller类上面添加@Validated注解,或者方法中字段前添加@Validated或@Valid注解。

    //类和方法上只要有一个地方使用@Validated即可
    //@Validated
    @RestController
    public class UserController {
    
        @Autowired
        private UserService userService;
    
        //方法上也可以使用@Validated
        @PostMapping(value = "/demo/users")
        public void createUser(@RequestBody @Valid User user) {
            userService.createUser(user);
        }
    }
    

    此外,@Validated和@Valid注解也可以放在UserService的接口中生效。

  • 对于Controller层请求参数的校验,需在Controller类上添加@Validated注解。

    @Validated
    @RestController
    public class UserController {
    
        @Autowired
        private UserService userService;
    
        @GetMapping("/demo/users/{name}")
        public User getUserByName(@PathVariable(value = "name")
                                  @Size(min = 3, max = 4) String name) {
            return userService.getUserByName(name);
        }
    }
    

@Validated和@Valid

这两个注解都可以使参数校验生效,但也有些区别:

区别 @Validated @Valid
依赖 org.springframework.validation.annotation.Validated javax.validation.Valid
作用目标 作用于类、方法和参数上,不能用于字段上 作用于方法、字段、构造函数、参数上
分组校验 支持 不支持
嵌套校验 不支持单独的嵌套校验,但可以和@Valid配合使用(@Valid用于字段上) 不支持单独的嵌套校验,但支持和@Valid或@Validated配合使用

嵌套校验

@Validated和@Valid注解都不具备单独进行嵌套校验的功能。

所谓的嵌套校验,就是需要校验某个实体类中定义的其他实体。例如,假设User类中定义了一个Family实体类的成员变量family,则需要在family字段上面添加@Valid注解才能使对family的校验生效。

@Data
public class User {
    @NotEmpty(message = "user name cannot be null or empty.")
    private String name;

    @Positive(message = "user age must larger than zero.")
    private int age;

    @Email(message = "email format must be correct.")
    private String email;

    //添加@Valid注解才能使Family实体中对address的校验注解生效
    @Valid
    private Family family;
}


@Data
public class Family {
    @NotBlank(message = "address must be not blank.")
    private String address;

    private int memberNum;
}

这样,只要在Controller层对User类参数添加@Validated或@Valid注解即可。

自定义注解参数校验

当内置的注解无法满足对参数的校验场景时,可以自定义注解进行参数校验。实现自定义注解参数校验通常分为以下三步:

​ 1)编写自定义注解

​ 2)实现注解校验类

​ 3)使用自定义注解

编写自定义注解

假设现在需要校验一个User类用户是否已成年,可以自定义一个这样的校验注解:

@Documented
@Target({TYPE, CONSTRUCTOR, PARAMETER})
@Retention(RUNTIME)
@Constraint(validatedBy = {AdultUserValidator.class})
public @interface AdultUserValidation {

    String message() default "";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};


    @Target({TYPE, CONSTRUCTOR, PARAMETER})
    @Retention(RUNTIME)
    @Documented
    public @interface List {
        AdultUserValidation[] value();
    }
}

相关注解介绍:

注解 用法说明 备注
@Documented 被此注解修饰的类,在生成文档时,会显示该类的内容
@Target 通过ElementType指定该注解可以作用哪些目标元素上 ElementType介绍详见下文
@Retention 保留注解的位置,由RetentionPolicy指定 RetentionPolicy介绍详见下文
@Constraint 用于限定自定义注解的使用范围,通过validatedBy指定实现注解校验的类

ElementType介绍:

ElementType是一个枚举类型,配合@Target注解用于指定注解可以使用在哪些目标元素上,具体枚举选项如下:

选项 说明
ElementType.TYPE 该注解可以作用在类、接口、枚举上
ElementType.FIELD 该注解只能作用在属性字段上
ElementType.METHOD 该注解只能作用在方法上
ElementType.PARAMETER 该注解只能作用在方法的参数上
ElementType.CONSTRUCTOR 该注解只能作用在类的构造器上
ElementType.LOCAL_VARIABLE 该注解只能作用在局部变量上
ElementType.ANNOTATION_TYPE 该注解只能作用在注解上
ElementType.PACKAGE 该注解只能作用在包上
ElementType.TYPE_PARAMETER 该注解可以作用在类的参数上
ElementType.TYPE_USE 该注解可以作用在类的任何语句上

RetentionPolicy介绍:

通常,注解的生命周期分为三个阶段:Java源文件 -> class文件 -> 内存中的字节码,这三个阶段分别可以通过RetentionPolicy的三个枚举类型指定,配合@Retention注解指定注解保留在什么地方,具体枚举选项如下:

选项 说明
RetentionPolicy.SOURCE 注解只被保留在源文件阶段,编译时会被丢弃
RetentionPolicy.CLASS 注解被保留在class文件阶段,但不会被加载到JVM中
RetentionPolicy.RUNTIME 注解被保留在源文件、class文件中,运行时会被加载到JVM中

实现注解校验类

实现@AdultUserValidation注解中的AdultUserValidator类如下:

public class AdultUserValidator implements ConstraintValidator<AdultUserValidation, User> {

    @Override
    public void initialize(AdultUserValidation constraintAnnotation) {
        //Do some initialization work before validation.
    }

    @Override
    public boolean isValid(User user, ConstraintValidatorContext context) {

        if (user == null) {
            return false;
        }

        return isAdultUser(user);
    }

    public boolean isAdultUser(User user) {
        return !user.getName().isEmpty() && user.getAge() >= 18;
    }
}

使用自定义注解

自定义校验注解的使用和内置注解的使用方式基本一致,在需要使用自定义注解的地方添加该注解,然后再Controller层添加@Validated或@Valid注解使其生效。

通常,对字段的校验需要在自定义注解的@Target中添加FIELD,然后在对应的字段上添加该注解;对实体类(例如User类)整体进行校验的注解会在注解的@Target中添加TYPE,然后就可以在User类前面添加自定义的注解

@AdultUserValidation
public class User {
  ...
}

自定义注解属性

在定义注解时,还可以根据需要来定义属性来实现特定的校验场景。例如,假设在User类中定义了一个gender字段来指定用户性别,gender字段只有Male和Female两个可选字段。

自定义一个@GenderValidation注解来校验gender字段,注解定义如下:

@Documented
@Target({FIELD, PARAMETER})
@Retention(RUNTIME)
@Constraint(validatedBy = {GenderValidator.class})
public @interface GenderValidation {

    String message() default "Gender must be Male or Female.";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};

    //自定义属性
    //校验字段的值必须在注解中指定的数组中才能校验通过
    String[] value() default {};


    @Documented
    @Target({TYPE, CONSTRUCTOR, PARAMETER})
    @Retention(RUNTIME)
    public @interface List {
        GenderValidation[] value();
    }
}

注解校验类GenderValidator如下:

public class GenderValidator implements ConstraintValidator<GenderValidation, String> {
    private List<String> genders;

    @Override
    public void initialize(GenderValidation constraintAnnotation) {
        this.genders = Arrays.asList(constraintAnnotation.value());
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        return genders.contains(value);
    }
}

然后,可以在User类的gender字段上添加注解@GenderValidation,如下所示:

@Data
public class User {
    ...
    //value属性指定gender的可选项只能为"Male"和"Female",否则校验不通过
    @GenderValidation(value = {"Male", "Female"}, 
                      message = "user gender must be Male or Female.")
    private String gender;
}

分组校验

@Validated和@Valid注解的区别之一就是前者支持分组校验。所谓的分组校验,可以理解为按照不同的分组或场景分别对相应的参数进行校验。要实现分组校验,可以分以下三步进行:

​ 1)定义分组接口或类

​ 2)在待校验参数的注解上指定分组类

​ 3)在Controller层添加@Validated注解并指定分组类

定义分组接口

定义以下两个分组校验接口,分别用于创建用户和更新用户时的校验。

public interface Create extends Default {
}

public interface Update extends Default {
}

这里继承了javax.validation.groups.Default接口,表示在进行Create/Update分组校验时,其他使用了javax.validation的Default分组的注解的地方也会生效

校验参数注解上指定分组类

User类的修改如下,参数name字段添加Create.class分组,参数email字段添加Update.class分组,通过注解的属性groups来指定。

@Data
public class User {

    @NotEmpty(message = "user name cannot be null or empty.", groups = Create.class)
    private String name;

    @Positive(message = "user age must larger than zero.")
    private int age;

    @Email(message = "email format must be correct.", groups = Update.class)
    private String email;
}

Controller层添加@Validated注解并指定分组类

@RestController
public class UserController {

    @Autowired
    private UserService userService;

    @PostMapping(value = "/demo/users")
    public void createUser(@RequestBody @Validated(Create.class) User user) {
        userService.createUser(user);
    }
    
    @PutMapping(value = "/demo/users")
    public void updateUser(@RequestBody @Validated(Update.class) User user) {
        userService.updateUser(user);
    }
}

至此,可以通过调用创建用户和更新用户接口进行测试。例如,通过验证可知,在调用createUser时,email字段不做校验,即不按照email格式仍然可以创建成功,而在调用updateUser时,该字段校验生效。

你可能感兴趣的:(java,SpringBoot,注解校验,spring,boot,java)