SpringBoot介面 - 如何優雅的對引數進行校驗？

在以SpringBoot開發Restful介面時, 對於介面的查詢引數後臺也是要進行校驗的，同時還需要給出校驗的返回資訊放到上文我們統一封裝的結構中。那麼如何優雅的進行引數的統一校驗呢？ @pdai

• SpringBoot介面 - 如何優雅的對引數進行校驗？
  • 什麼是不優雅的引數校驗
  • 實現案例
    • POM
    • 請求引數封裝
    • Controller中獲取引數繫結結果
    • 校驗結果
  • 進一步理解
    • Validation分組校驗？
    • @Validate和@Valid什麼區別？
    • 有哪些常用的校驗？
    • 自定義validation？
  • 示例原始碼
  • 更多內容

什麼是不優雅的引數校驗

後端對前端傳過來的引數也是需要進行校驗的，如果在controller中直接校驗需要用大量的if else做判斷

以新增使用者的介面為例，需要對前端傳過來的引數進行校驗， 如下的校驗就是不優雅的：

@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");
    }
}

針對這個普遍的問題，Java開者在Java API規範 (JSR303) 定義了Bean校驗的標準validation-api，但沒有提供實現。

hibernate validation是對這個規範的實現，並增加了校驗註解如@Email、@Length等。

Spring Validation是對hibernate validation的二次封裝，用於支援spring mvc引數自動校驗。

接下來，我們以springboot專案為例，介紹Spring Validation的使用。

實現案例

本例子採用 spring validation 對引數繫結進行校驗，主要給你提供引數校驗的思路。針對介面統一的錯誤資訊（比如繫結引數檢查的錯誤）封裝請看SpringBoot介面 - 如何統一異常處理。

POM

新增pom依賴

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

請求引數封裝

單一職責，所以將查詢使用者的引數封裝到UserParam中， 而不是User（資料庫實體）本身。

對每個引數欄位新增validation註解約束和message。

/**
 * 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;

}

Controller中獲取引數繫結結果

使用@Valid或者@Validate註解，引數校驗的值放在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");
    }
}

校驗結果

POST訪問新增User的請求

後臺輸出引數繫結錯誤資訊：（包含哪個物件，哪個欄位，什麼樣的錯誤描述）

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

（本例只是springboot-validation的簡單用例，針對介面統一的錯誤資訊封裝請看SpringBoot介面 - 如何統一異常處理

進一步理解

我們再通過一些問題來幫助你更深入理解validation校驗。@pdai

Validation分組校驗？

上面的例子中，其實存在一個問題，UserParam既可以作為addUser的引數（id為空），又可以作為updateUser的引數（id不能為空），這時候怎麼辦呢？分組校驗登場。

@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;

}

這時候可以使用Validation分組

• 先定義分組（無需實現介面）

public interface AddValidationGroup {
}
public interface EditValidationGroup {
}

• 在UserParam的userId欄位新增分組

@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;

}

• controller中的介面使用校驗時使用分組

PS: 需要使用@Validated註解

@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);
    }
}

• 測試

@Validate和@Valid什麼區別？

細心的你會發現，上個例子中用的是@Validate, 而不是@Valid，那它們之間的區別是什麼呢？

在檢驗Controller的入參是否符合規範時，使用@Validated或者@Valid在基本驗證功能上沒有太多區別。但是在分組、註解地方、巢狀驗證等功能上兩個有所不同：

• 分組

@Validated：提供了一個分組功能，可以在入參驗證時，根據不同的分組採用不同的驗證機制，這個網上也有資料，不詳述。@Valid：作為標準JSR-303規範，還沒有吸收分組的功能。

• 註解地方

@Validated：可以用在型別、方法和方法引數上。但是不能用在成員屬性（欄位）上

@Valid：可以用在方法、建構函式、方法引數和成員屬性（欄位）上

• 巢狀型別

比如本文例子中的address是user的一個巢狀屬性, 只能用@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;

}

有哪些常用的校驗？

從以下三類理解。

• JSR303/JSR-349: JSR303是一項標準,只提供規範不提供實現，規定一些校驗規範即校驗註解，如@Null，@NotNull，@Pattern，位於javax.validation.constraints包下。JSR-349是其的升級版本，新增了一些新特性。

@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是對這個規範的實現，並增加了一些其他校驗註解，如@Email，@Length，@Range等等

@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對hibernate validation進行了二次封裝，在springmvc模組中新增了自動校驗，並將校驗資訊封裝進了特定的類中

自定義validation？

如果上面的註解不能滿足我們檢驗引數的要求，我們能不能自定義校驗規則呢？ 可以。

• 定義註解

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 { };
}

• 定義校驗器

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;
        }
    }

}

• 使用

@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;

}

示例原始碼

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

更多內容

告別碎片化學習，無套路一站式體系化學習後端開發: Java 全棧知識體系(https://pdai.tech)