gogoWebsite

1. Application scenarios

In actual working projects, we often encounter parameter verification problems. For example, we only allow the front-end to pass to us in the status field.0,1,2These three values, for exampletimeUnitWe only allow front-end to pass fields to usm,h,dThese three values ​​are often encountered in this kind of scenario. When doing projects, you may not have much requirements for parameter verification, but in actual work, parameter verification is very important. What we want to talk about today is how to verify the enumeration value of the parameter. Before this, let’s take a look at how to use the annotation verification.

2. Review the use of annotation verification

1. Import dependencies

<dependency>
    <groupId></groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

2. Use annotations to verify the parameters passed in front-end

@Data
public class DocAddReqVo {

    @NotBlank(message = "Document name cannot be empty")
    @Pattern(regexp =  "^[^\"'&<>()+%\\\\]{0,95}$", message = "The document name cannot contain special characters such as \"'&<>()+% and cannot exceed 95 characters")
    private String name;

    @NotBlank(message = "Category id cannot be empty")
    private String categoryId;

    @NotEmpty(message = "Document tag cannot be empty")
    private Set<String> tags;

    @Length(max = 5000, message = "The text content cannot exceed 5000 characters")
    @NotBlank(message = "The document content cannot be empty")
    private String content;

}

3. After marking verification annotation on the entity class, be sure to enable the verification function @Valid

@RestController
@Slf4j
@RequestMapping("/api/v1")
public class DocController implements CommonConstant {

    @Autowired
    private DocService docService;

    // Annotate @Valid annotation
    @PostMapping("/docs")
    public DocAddRespVo add(@RequestBody @Valid DocAddReqVo docAddReqVo) {
        Doc doc = docService.addDoc(new Doc(docAddReqVo));
        return new DocAddRespVo(doc.getId());
    }
}

This is the whole process of annotation verification. Of course, there are many other annotations and usage methods. This is not the focus of our attention today and will not be extended.

3. Custom annotation to verify integer enum value

Requirement: If there is a field status to identify the product's up and down, the up and down represents 0, and the down and down represents 1, it stipulates that the parameters sent to us by the front end can only be0,1These two values ​​cannot be passed in other values ​​such as 3, 4, 5, etc. otherwise the verification will not be passed, so an annotation can be implemented.

Goal: Implement annotation@AllowValue, this annotation has a property vals, vals can only be passed into0,1

1. Customize annotation@AllowValue ：

@Target({ ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE, ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE })
@Retention(RetentionPolicy.RUNTIME)
@Documented
// Need to customize a verification device AllowConstraintValidator
@Constraint(validatedBy = { AllowConstraintValidator.class })
public @interface AllowValue {
    // Prompt message for inspection failure
    String message() default "{}";

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

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

    // Annotation properties
    int[] vals() default {};
}

**2. Customize a verification device AllowConstraintValidator **

public class AllowConstraintValidator implements ConstraintValidator<AllowValue, Integer> {
    // @AllowValue(vals = { 0, 1 }, message = "status can only be 0 and 1"), put the checked enum value into set
    Set<Integer> set = new HashSet<>();

    @Override
    public void initialize(AllowValue constraintAnnotation) {
        // Annotation properties
        int[] vals = constraintAnnotation.vals();
        for (int value : vals) {
            set.add(value);
        }
    }

    /**
      * Determine whether the verification is successful
      * @param value The value to be checked
      */
    @Override
    public boolean isValid(Integer value, ConstraintValidatorContext context) {
        // If the set contains the value to be checked, it means that the verification is passed, otherwise the verification fails
        return value == null || set.contains(value);
    }
}

3. Use annotation verification

@Data
public class AttachmentAddReqVo {

    @NotNull(message = "Category cannot be empty")
    // vals = { 0, 1 }, which means that only the front-end is allowed to pass in two values: 0 and 1
    @AllowValue(vals = { 0, 1 }, message = "status can only be 0 and 1")
    private int status;
    
}

The above custom annotation vals is an integer array, which can only verify the integer value. So what if we want to verify both the integer value and the string? More general annotation verification is needed

4. Custom annotation to verify enum values ​​of various types

If there is a field status to identify the product's up and down, the up and down represents 0, and the down and down represents 1

4.1 Use Example 1

Requirements: Specifies that the parameters passed to us by the front end can only be0、1These two values ​​cannot be passed in other values ​​(null values ​​are not allowed), otherwise the verification will not be passed

1. Define an enumeration class and enumerate the values ​​allowed to be incorporated at the front end: 0 and 1

public enum  AllowIntValueEnum {
    /**
      * Product list and remove enumeration
      */
    UP(0),
    DOWN(1);

    private int value;

    AllowIntValueEnum(int value){
        this.value = value;
    }

    public int getValue() {
        return value;
    }
}

2. Use custom annotation @Enum verification:

@Data
public class DemoEntity {
    // clazz: The name of the enumeration class
    // method: Get the method name of the field to be checked in the enumeration class
    // allowNull: Whether to allow null value
    // message: Prompt message when the verification fails
    @Enum(clazz = AllowIntValueEnum.class,method = "getValue",allowNull = false,message = "Only pass in enum values ​​0 and 1")
    private int status;
}

4.2 Use Example 2

Requirements: Specifies that the parameters passed to us by the front end can only beOn-the-shelf, off-the-shelfThese two values ​​cannot be passed in other values ​​(null values ​​allow), otherwise the verification will not be passed

1. Define an enumeration class and enumerate the values ​​allowed by the front end: list and remove

public enum AllowStringValueEnum {
    /**
      * Product list and remove enumeration
      */
    UP("On the shelves"),
    DOWN("Offset");

    private String message;

    AllowStringValueEnum(String message){
        this.message = message;
    }

    public String getMessage() {
        return message;
    }
}

2. Use custom annotation @Enum verification:

@Data
public class DemoEntity {
    // clazz: The name of the enumeration class
    // method: Get the method name of the field to be checked in the enumeration class
    // allowNull: Whether to allow null value
    // message: Prompt message when the verification fails
    @Enum(clazz = AllowStringValueEnum.class,method = "getMessage",allowNull = true,message = "Only incoming enum values ​​are allowed to be listed and removed")
    private String name;
}

4.3 Use Example 3

Requirements: Specifies that the parameters passed to us by the front end can only beOn-the-shelf, off-the-shelfThese two values ​​cannot be passed in other values ​​(null values ​​are not allowed), otherwise the verification will not be passed

1. Define an enumeration class and enumerate the values ​​allowed by the front end: list and remove

public enum AllowValueEnum {
    /**
      * Product list and remove enumeration
      */
     UP(0,"On the shelves"),
     DOWN(1,"Offset");

     private int value;
     private String message;
     AllowValueEnum(int value,String message){
         this.value = value;
         this.message = message;
     }

     public int getValue() {
        return value;
     }

     public String getMessage() {
        return message;
     }
}

2. Use custom annotation @Enum verification:

@Data
public class DemoEntity {
    // clazz: The name of the enumeration class
    // method: Get the method name of the field to be checked in the enumeration class
    // allowNull: Whether to allow null value
    // message: Prompt message when the verification fails
    @Enum(clazz = AllowValueEnum.class,method = "getMessage",allowNull = false,message = "Only incoming enum values ​​are allowed to be listed and removed")
    private String status;
}

How about it? After reading the verification method above, does it feel very convenient? So how is this annotation implemented? Let's take a look together

4.4 Implement custom annotations

1. Customize annotation@Enum

@Documented
@Target({ ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE, ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE })
@Retention(RetentionPolicy.RUNTIME)
@Repeatable(Enum.List.class)
@Constraint(validatedBy = { EnumValidator.class })
public @interface Enum {

    String message() default "{*.}";

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

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

    /**
      * Enumeration class to be verified
      *
      * @return enumeration class
      */
    Class<?> clazz();

    /**
      * To verify which field of the enumeration class, this field is obtained through the getxxx() method and returns the method name
      *
      * @return method name
      */
    String method() default "ordinal";

    /**
      * Whether to allow null value, the default is to allow
      */
    boolean allowNull() default true;
    
    @Documented
    @Target({ ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE, ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE })
    @Retention(RetentionPolicy.RUNTIME)
    @interface List {
        Enum[] value();
    }
}

2. Customize annotation checkerEnumValidator

public class EnumValidator implements ConstraintValidator<Enum,Object> {

    private Enum annotation;

    @Override
    public void initialize(Enum constraintAnnotation) {
        this.annotation = constraintAnnotation;
    }

    /**
      * Determine whether the verification is successful
      * @param value The value to be checked
      * @return Verification result
      */
    @Override
    public boolean isValid(Object value, ConstraintValidatorContext context) {
        // If the value to be checked is null, will the verification be passed
        if (value == null) {
            return annotation.allowNull();
        }
        // Return an array of enumeration constants: UP, DOWN
        Object[] objects = annotation.clazz().getEnumConstants();
        try {
            // Get the method name of the check field in the enumeration class
            Method method = annotation.clazz().getMethod(annotation.method());
            for (Object o : objects) {
                // Compare the result of the method execution (o) with the value to be checked. If the same is true, it means that the verification is successful
               if (value.equals(method.invoke(o))) {
                    return true;
                }
            }
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
        // If the value is not in the enum value, the verification fails
        return false;
    }
}

5. Custom annotation checks integer and string type enumeration values

It is also OK if you don't want to write an enumeration class and want to verify the enumeration value of a string type.

1. Custom annotations

@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = { EnumValueValidator.class })
public @interface EnumValue {
    // Default error message
    String message() default "Must be specified";

    // String type
    String[] strValues() default {};

    // Integer
    int[] intValues() default {};

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

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

    // Use when specifying multiple
    @Target({ FIELD, METHOD, PARAMETER, ANNOTATION_TYPE })
    @Retention(RUNTIME)
    @Documented
    @interface List {
        EnumValue[] value();
    }
}

2. Customize the checker

public class EnumValueValidator implements ConstraintValidator<EnumValue, Object> {

    private String[] strValues;

    private int[] intValues;

    @Override
    public void initialize(EnumValue constraintAnnotation) {
        strValues = constraintAnnotation.strValues();
        intValues = constraintAnnotation.intValues();
    }

    @Override
    public boolean isValid(Object value, ConstraintValidatorContext constraintValidatorContext) {
        if (Objects.isNull(value)) {
            return true;
        }
        if (value instanceof String) {
            for (String s : strValues) {
                if (s.equals(value)) {
                    return true;
                }
            }
        } else if (value instanceof Integer) {
            for (Integer s : intValues) {
                if (s == value) {
                    return true;
                }
            }
        }
        return false;
    }
}

3. Verify using custom annotations

@Data
public class DemoEntity {
    @EnumValue(strValues = { "On the shelves", "Offset"},message = "Only incoming enum values ​​are allowed to be listed and removed")
    private String name;
}