SpringBoot Interface - How to Validate Parameters Elegantly?

When developing a Restful interface with SpringBoot, the query parameter background of the interface also needs to be verified, and the return information of the verification needs to be given in the structure we uniformly encapsulated above. So how to elegantly perform unified verification of parameters? @pdai

• SpringBoot Interface - How to Validate Parameters Elegantly?

  • What is inelegant parameter validation

  • Implementation case

    • POM
    • Request parameter encapsulation
    • Get parameter binding result in Controller
    • Check result

  • further understanding

    • Validation group validation?
    • What is the difference between @Validate and @Valid?
    • What are the commonly used calibrations?
    • Custom validation?
  • Sample source code
  • more content

What is inelegant parameter validation

The back-end also needs to verify the parameters passed from the front-end. If it is directly verified in the controller, a lot of if else is needed to make judgments.

Taking the interface for adding users as an example, the parameters passed from the front end need to be verified. The following verification is not elegant:

 @RestController
@RequestMapping("/user")
public class UserController {

    @PostMapping("add")
    public ResponseEntity<String> add(User user) {
        if(user.getName()==null) {
            return ResponseResult.fail("user name should not be empty");
        } else if(user.getName().length()<5 || user.getName().length()>50){
            return ResponseResult.fail("user name length should between 5-50");
        }
        if(user.getAge()< 1 || user.getAge()> 150) {
            return ResponseResult.fail("invalid age");
        }
        // ...
        return ResponseEntity.ok("success");
    }
}

In response to this common problem, the Java developers defined the standard validation-api for Bean validation in the Java API Specification (JSR303), but did not provide an implementation.

hibernate validation is an implementation of this specification and adds validation annotations such as @Email, @Length, etc.

Spring Validation is a secondary encapsulation of hibernate validation to support automatic validation of spring mvc parameters.

Next, we take the springboot project as an example to introduce the use of Spring Validation.

Implementation case

This example uses spring validation to verify the parameter binding, mainly to provide you with the idea of parameter verification. For the encapsulation of unified error information for interfaces (such as errors in bound parameter checking), see SpringBoot Interface - How to Unify Exception Handling .

POM

add pom dependencies

 <!-- https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-validation -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

Request parameter encapsulation

Single responsibility, so the parameters of the query user are encapsulated into UserParam, rather than User (database entity) itself.

Add validation annotation constraints and message to each parameter field.

 /**
 * user.
 *
 * @author pdai
 */
@Data
@Builder
@ApiModel(value = "User", subTypes = {AddressParam.class})
public class UserParam implements Serializable {

    private static final long serialVersionUID = 1L;

    @NotEmpty(message = "could not be empty")
    private String userId;

    @NotEmpty(message = "could not be empty")
    @Email(message = "invalid email")
    private String email;

    @NotEmpty(message = "could not be empty")
    @Pattern(regexp = "^(\\d{6})(\\d{4})(\\d{2})(\\d{2})(\\d{3})([0-9]|X)$", message = "invalid ID")
    private String cardNo;

    @NotEmpty(message = "could not be empty")
    @Length(min = 1, max = 10, message = "nick name should be 1-10")
    private String nickName;

    @NotEmpty(message = "could not be empty")
    @Range(min = 0, max = 1, message = "sex should be 0-1")
    private int sex;

    @Max(value = 100, message = "Please input valid age")
    private int age;

    @Valid
    private AddressParam address;

}

Get parameter binding result in Controller

Use @Valid or @Validate annotation, the value of parameter validation is placed in BindingResult

 /**
 * @author pdai
 */
@Slf4j
@Api(value = "User Interfaces", tags = "User Interfaces")
@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * http://localhost:8080/user/add .
     *
     * @param userParam user param
     * @return user
     */
    @ApiOperation("Add User")
    @ApiImplicitParam(name = "userParam", type = "body", dataTypeClass = UserParam.class, required = true)
    @PostMapping("add")
    public ResponseEntity<String> add(@Valid @RequestBody UserParam userParam, BindingResult bindingResult) {
        if (bindingResult.hasErrors()) {
            List<ObjectError> errors = bindingResult.getAllErrors();
            errors.forEach(p -> {
                FieldError fieldError = (FieldError) p;
                log.error("Invalid Parameter : object - {},field - {},errorMessage - {}", fieldError.getObjectName(), fieldError.getField(), fieldError.getDefaultMessage());
            });
            return ResponseEntity.badRequest().body("invalid parameter");
        }
        return ResponseEntity.ok("success");
    }
}

Check result

POST access to add User's request

Background output parameter binding error information: (which object, which field, and what kind of error description)

 2021-09-16 10:37:05.173 ERROR 21216 --- [nio-8080-exec-8] t.p.s.v.controller.UserController        : Invalid Parameter : object - userParam,field - nickName,errorMessage - could not be empty
2021-09-16 10:37:05.176 ERROR 21216 --- [nio-8080-exec-8] t.p.s.v.controller.UserController        : Invalid Parameter : object - userParam,field - email,errorMessage - could not be empty
2021-09-16 10:37:05.176 ERROR 21216 --- [nio-8080-exec-8] t.p.s.v.controller.UserController        : Invalid Parameter : object - userParam,field - cardNo,errorMessage - could not be empty

(This example is just a simple use case of springboot-validation. For the unified error message encapsulation of the interface, please see SpringBoot Interface - How to Unify Exception Handling

further understanding

Let's go through some questions to help you better understand validation. @pdai

Validation group validation?

In the above example, there is actually a problem. UserParam can be used as a parameter of addUser (id is empty), and can be used as a parameter of updateUser (id cannot be empty). What should I do at this time? Packet check comes on stage.

 @Data
@Builder
@ApiModel(value = "User", subTypes = {AddressParam.class})
public class UserParam implements Serializable {

    private static final long serialVersionUID = 1L;

    @NotEmpty(message = "could not be empty") // 这里定为空，对于addUser时是不合适的
    private String userId;

}

At this time, you can use Validation grouping

• Define the group first (no need to implement the interface)

 public interface AddValidationGroup {
}
public interface EditValidationGroup {
}

• Add grouping in the userId field of UserParam

 @Data
@Builder
@ApiModel(value = "User", subTypes = {AddressParam.class})
public class UserParam implements Serializable {

    private static final long serialVersionUID = 1L;

    @NotEmpty(message = "{user.msg.userId.notEmpty}", groups = {EditValidationGroup.class}) // 这里
    private String userId;

}

• The interface in the controller uses the grouping when using the verification

PS: need to use @Validated annotation

 @Slf4j
@Api(value = "User Interfaces", tags = "User Interfaces")
@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * http://localhost:8080/user/add .
     *
     * @param userParam user param
     * @return user
     */
    @ApiOperation("Add User")
    @ApiImplicitParam(name = "userParam", type = "body", dataTypeClass = UserParam.class, required = true)
    @PostMapping("add")
    public ResponseEntity<UserParam> add(@Validated(AddValidationGroup.class) @RequestBody UserParam userParam) {
        return ResponseEntity.ok(userParam);
    }

    /**
     * http://localhost:8080/user/add .
     *
     * @param userParam user param
     * @return user
     */
    @ApiOperation("Edit User")
    @ApiImplicitParam(name = "userParam", type = "body", dataTypeClass = UserParam.class, required = true)
    @PostMapping("edit")
    public ResponseEntity<UserParam> edit(@Validated(EditValidationGroup.class) @RequestBody UserParam userParam) {
        return ResponseEntity.ok(userParam);
    }
}

• test

What is the difference between @Validate and @Valid?

If you are careful, you will find that @Validate is used instead of @Valid in the previous example. What is the difference between them?

There is not much difference in the basic validation function of using @Validated or @Valid when checking whether the input parameters of the Controller conform to the specification. However, the two are different in functions such as grouping, annotation, and nested validation:

• grouping

@Validated: Provides a grouping function, which can use different verification mechanisms according to different groups when entering parameters for verification. There are also information on this website, which will not be described in detail. @Valid: As a standard JSR-303 specification, there is no feature to absorb grouping yet.

• Annotation place

@Validated: Can be used on types, methods and method parameters. But it cannot be used on member properties (fields)

@Valid: can be used on methods, constructors, method parameters and member properties (fields)

• nested type

For example, the address in the example of this article is a nested attribute of user, which can only be used with @Valid

 @Data
@Builder
@ApiModel(value = "User", subTypes = {AddressParam.class})
public class UserParam implements Serializable {

    private static final long serialVersionUID = 1L;

    @Valid // 这里只能用@Valid
    private AddressParam address;

}

What are the commonly used calibrations?

Understand from the following three categories.

• JSR303/JSR-349 : JSR303 is a standard that only provides specifications but not implementations. It specifies some verification specifications, namely verification annotations, such as @Null, @NotNull, @Pattern, located in the javax.validation.constraints package. JSR-349 is an upgraded version with some new features added .

 @AssertFalse            被注释的元素只能为false
@AssertTrue             被注释的元素只能为true
@DecimalMax             被注释的元素必须小于或等于{value}
@DecimalMin             被注释的元素必须大于或等于{value}
@Digits                 被注释的元素数字的值超出了允许范围(只允许在{integer}位整数和{fraction}位小数范围内)
@Email                  被注释的元素不是一个合法的电子邮件地址
@Future                 被注释的元素需要是一个将来的时间
@FutureOrPresent        被注释的元素需要是一个将来或现在的时间
@Max                    被注释的元素最大不能超过{value}
@Min                    被注释的元素最小不能小于{value}
@Negative               被注释的元素必须是负数
@NegativeOrZero         被注释的元素必须是负数或零
@NotBlank               被注释的元素不能为空
@NotEmpty               被注释的元素不能为空
@NotNull                被注释的元素不能为null
@Null                   被注释的元素必须为null
@Past                   被注释的元素需要是一个过去的时间
@PastOrPresent          被注释的元素需要是一个过去或现在的时间
@Pattern                被注释的元素需要匹配正则表达式"{regexp}"
@Positive               被注释的元素必须是正数
@PositiveOrZero         被注释的元素必须是正数或零
@Size                   被注释的元素个数必须在{min}和{max}之间

• hibernate validation : hibernate validation is an implementation of this specification and adds some other validation annotations, such as @Email, @Length, @Range, etc.

 @CreditCardNumber       被注释的元素不合法的信用卡号码
@Currency               被注释的元素不合法的货币 (必须是{value}其中之一)
@EAN                    被注释的元素不合法的{type}条形码
@Email                  被注释的元素不是一个合法的电子邮件地址  (已过期)
@Length                 被注释的元素长度需要在{min}和{max}之间
@CodePointLength        被注释的元素长度需要在{min}和{max}之间
@LuhnCheck              被注释的元素${validatedValue}的校验码不合法, Luhn模10校验和不匹配
@Mod10Check             被注释的元素${validatedValue}的校验码不合法, 模10校验和不匹配
@Mod11Check             被注释的元素${validatedValue}的校验码不合法, 模11校验和不匹配
@ModCheck               被注释的元素${validatedValue}的校验码不合法, ${modType}校验和不匹配  (已过期)
@NotBlank               被注释的元素不能为空  (已过期)
@NotEmpty               被注释的元素不能为空  (已过期)
@ParametersScriptAssert 被注释的元素执行脚本表达式"{script}"没有返回期望结果
@Range                  被注释的元素需要在{min}和{max}之间
@SafeHtml               被注释的元素可能有不安全的HTML内容
@ScriptAssert           被注释的元素执行脚本表达式"{script}"没有返回期望结果
@URL                    被注释的元素需要是一个合法的URL
@DurationMax            被注释的元素必须小于${inclusive == true ? '或等于' : ''}${days == 0 ? '' : days += '天'}${hours == 0 ? '' : hours += '小时'}${minutes == 0 ? '' : minutes += '分钟'}${seconds == 0 ? '' : seconds += '秒'}${millis == 0 ? '' : millis += '毫秒'}${nanos == 0 ? '' : nanos += '纳秒'}
@DurationMin            被注释的元素必须大于${inclusive == true ? '或等于' : ''}${days == 0 ? '' : days += '天'}${hours == 0 ? '' : hours += '小时'}${minutes == 0 ? '' : minutes += '分钟'}${seconds == 0 ? '' : seconds += '秒'}${millis == 0 ? '' : millis += '毫秒'}${nanos == 0 ? '' : nanos += '纳秒'}

• spring validation : spring validation encapsulates hibernate validation twice, adds automatic validation to the springmvc module, and encapsulates the validation information into a specific class

Custom validation?

If the above annotations cannot meet the requirements of our verification parameters, can we customize the verification rules? Can.

• define annotations

 package tech.pdai.springboot.validation.group.validation.custom;

import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = {TelephoneNumberValidator.class}) // 指定校验器
public @interface TelephoneNumber {
    String message() default "Invalid telephone number";
    Class<?>[] groups() default { };
    Class<? extends Payload>[] payload() default { };
}

• define validator

 public class TelephoneNumberValidator implements ConstraintValidator<TelephoneNumber, String> {
    private static final String REGEX_TEL = "0\\d{2,3}[-]?\\d{7,8}|0\\d{2,3}\\s?\\d{7,8}|13[0-9]\\d{8}|15[1089]\\d{8}";

    @Override
    public boolean isValid(String s, ConstraintValidatorContext constraintValidatorContext) {
        try {
            return Pattern.matches(REGEX_TEL, s);
        } catch (Exception e) {
            return false;
        }
    }

}

• use

 @Data
@Builder
@ApiModel(value = "User", subTypes = {AddressParam.class})
public class UserParam implements Serializable {

    private static final long serialVersionUID = 1L;

    @NotEmpty(message = "{user.msg.userId.notEmpty}", groups = {EditValidationGroup.class})
    private String userId;

    @TelephoneNumber(message = "invalid telephone number") // 这里
    private String telephone;

}

Sample source code

https://github.com/realpdai/tech-pdai-spring-demos

more content

Java Full Stack Knowledge System (https://pdai.tech)