10、SpringBoot參數校驗

1、概述

JSR相關的概念就不贅述了，網上一搜一大把。只要知道以下內容的區別即可：

• Bean Validation，（javax.validation）包下的接口規范。
• Hibernate Validation，Hibernate對於上述規范的具體實現。
• Spring Validation，是對Hibernate的二次封裝，在Spring環境中使用起來更為方便。

今天主要總結SpringBoot中進行參數校驗的幾種方案。

2、注解說明

常用的注解有：@NotNull、@NotEmpty、@NotBlank、@Email、@Pattern、@Past、@Size、@Min、@Max

• @NotNull

可以注釋在任何類型的變量上，而且不能是基本類型，必須是基本類型對應的包裝類，否則不起作用
例如：

@NotNull(message = "不能為空")
private int times;

雖然程序可以正常運行，不報錯，但是@NotNull注解並不起作用，因為times是基本類型，且是成員變量，默認值為0。

修改成：

@NotNull(message = "不能為空")
private Integer times;

即可生效。

• @NotEmpty和@NotBlank

這兩個注解需要放在一起理解，都是表示變量不為空
這兩個注解都是架在字符串類型的變量上，且不能用於其他類型，否則運行時會報錯。
區別在於：
@NotEmpty不會去掉空白字符， 例如變量為 “”會報錯，而 “  ”就不會報錯
@NotBlank會自動去掉空白字符，不管是“ ”還是“      ”，在它眼里都是“”，都會報錯。

• @Email、@Pattern、@Past、@Size、@Min 和 @Max

這幾個注解可以放在一起看，在不同的場景下，使用不同的注解
1、@Email：加在字符串上，用來校驗是否滿足郵箱格式。
2、@Pattern：按照正則表達式來校驗
3、@Past：加在日期格式上，用來表示不能是未來的日期，只能是過去的日期
4、@Size：表示集合的數量大小
例如
@Size(min = 1, message = "不能少於1個好友")
private List<UserInfo>friends;
5、@Min和@Max
加在整形上，表示數值的上下限，對於基本類型（int），也是有效的

注意點：
上述的幾個注解並不能保證數據不為null，如果需要保證數據不為null，必須配合@NotNull標簽
例如
@Past(message = "時間不能是未來的時間")
@NotNull(message = "日期不能不填")
private Date birthday;

• 嵌套校驗

  @Size(min = 1, message = "不能少於1個好友") //為空時不會報錯
  private List<@Valid UserInfo>friends;

 

3、非Spring環境測試Demo

3.1、依賴

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.11</version>
      <scope>test</scope>
    </dependency>

    <dependency>
      <groupId>javax.validation</groupId>
      <artifactId>validation-api</artifactId>
      <version>2.0.1.Final</version>
    </dependency>

    <dependency>
      <groupId>org.hibernate.validator</groupId>
      <artifactId>hibernate-validator</artifactId>
      <version>6.1.5.Final</version>
    </dependency>

    <dependency>
      <groupId>javax.el</groupId>
      <artifactId>javax.el-api</artifactId>
      <version>3.0.0</version>
    </dependency>

    <dependency>
      <groupId>org.glassfish.web</groupId>
      <artifactId>javax.el</artifactId>
      <version>2.2.6</version>
    </dependency>

 

3.2、pojo類

public class UserInfo {

    public interface UpdateGroup {}

    public interface InsertGroup {}

    @NotNull(message = "用戶id不能為空", groups = {UpdateGroup.class})
    private String userId;

    //依次驗證每個組
    @GroupSequence({
            UpdateGroup.class,
            InsertGroup.class,
            Default.class
    })
    public interface group {}


    @NotEmpty(message = "用戶名不能為空")  //不會自動去掉前后空格
    private String userName;

    //有多個條件時，如果都不滿足，會打印所有信息
    @NotBlank(message = "用戶密碼不能為空")  //會自動去掉字符串中的空格
    @Length(min = 6, max = 20, message = "密碼不能少於6位，多於20位")
    private String password;

    @Email(message = "必須為有效郵箱")  //為空時不會報錯
    private String email;

    @Pattern(regexp = "^[1][3,4,5,6,7,8,9][0-9]{9}$", message = "手機號格式有誤")
    private String phone;

    @Min(value = 18, message = "年齡必須大於18歲")
    @Max(value = 68, message = "年齡必須小於68歲") //為空時不會報錯
    private Integer age;

    @Past(message = "時間不能是未來的時間")
    @NotNull(message = "日期不能不填")
    private Date birthday;

    @Size(min = 1, message = "不能少於1個好友") //為空時不會報錯
    private List<UserInfo>friends;

    public String getUserId() {
        return userId;
    }

    public void setUserId(String userId) {
        this.userId = userId;
    }

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone;
    }

    public Date getBirthday() {
        return birthday;
    }

    public void setBirthday(Date birthday) {
        this.birthday = birthday;
    }

    public List<UserInfo> getFriends() {
        return friends;
    }

    public void setFriends(List<UserInfo> friends) {
        this.friends = friends;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }
    
    @Override
    public String toString() {
        return "UserInfo{" +
                "userId='" + userId + '\'' +
                ", userName='" + userName + '\'' +
                ", password='" + password + '\'' +
                ", email='" + email + '\'' +
                ", phone='" + phone + '\'' +
                ", age=" + age +
                ", birthday=" + birthday +
                ", friends=" + friends +
                '}';
    }
}

3.3 分組

以前一直有一個疑惑，validation參數校驗確實很方便，但是某些情況下並不能滿足開發需求。

比如添加用戶信息和更新用戶信息這兩個業務場景下，添加用戶信息不需要傳入用戶id，一般后台生成，而更新用戶信息時必須傳入用戶id。這兩種情況對userId這個字段的要求不一樣。

validation校驗框架提供了一種策略——分組，將不同的校驗方式划分在不同的分組下。例如：

@NotNull(message = "用戶id不能為空", groups = {UpdateGroup.class})
private String userId;

該標簽只有在分組為 UpdateGroup.class時，才生效。這里的字節碼僅僅時用來區分不同的分組、表示唯一性，沒有特殊的含義。（可以聯想到synchronized）。

因為沒什么含義，為了方便，在上述pojo類里面添加了兩個接口

public interface UpdateGroup {}

public interface InsertGroup {}

為了減少耦合，也可以將這兩個接口定在外面。

其實validation已經的默認分組為Default.class，所以就算是不指定分組，也會被自動的划分到Default.class分組下（聯想到Object類）。

在使用的時候，可以指定一個或者多個分組：

    @Test
    public void groupValidation(){
        set = validator.validate(userInfo, UserInfo.UpdateGroup.class, Default.class);
    }

完整的測試Demo見下方的測試類。這種寫法表示按照 UpdateGroup和Default分組進行校驗。

當涉及多個分組的時候，就會出現一個校驗順序的問題，我們可以指定分組順序，讓框架按照我們自定義的順序依次校驗：

    //依次驗證每個組
    @GroupSequence({
            UpdateGroup.class,
            InsertGroup.class,
            Default.class
    })
    public interface group {}

 

3.4 測試類

/**
 * 驗證測試類
 */
public class ValidationTest {

    private Validator validator;

    private UserInfo userInfo;

    private Set<ConstraintViolation<UserInfo>> set;

    /**
     * 初始化操作
     */
    @Before
    public void init() {
        validator = Validation.buildDefaultValidatorFactory().getValidator();
        userInfo = new UserInfo();
        userInfo.setUserId("123");
        userInfo.setUserName(" ");
        userInfo.setPassword("1234576");
        userInfo.setEmail("[e-mail]");
        userInfo.setAge(70);
        Calendar calendar = Calendar.getInstance();
        calendar.set(1968, Calendar.FEBRUARY,1);
        userInfo.setBirthday(calendar.getTime());
        userInfo.setFriends(new ArrayList() {{add(new UserInfo());}});
    }

    /**
     * 結果打印
     */
    @After
    public void print(){
        set.forEach(item -> {
            //輸出錯誤信息
            System.out.println(item.getMessage());
        });
    }

    @Test
    public void nullValidation(){
        //用驗證器對對象進行驗證
        set = validator.validate(userInfo);
    }

    @Test
    public void groupValidation(){
        set = validator.validate(userInfo, UserInfo.UpdateGroup.class, Default.class);
    }
}

4、Spring環境Demo

4.1 環境說明

SpringBoot版本：

 <version>2.3.4.RELEASE</version>

依賴

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

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
    <exclusions>
        <exclusion>
            <groupId>org.junit.vintage</groupId>
            <artifactId>junit-vintage-engine</artifactId>
        </exclusion>
    </exclusions>
</dependency>


<!--validation相關-->
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.1.5.Final</version>
</dependency>

<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
</dependency>

4.2 pojo類

public class UserInfo {

    @NotNull(message = "用戶id不能為空", groups = {UpdateGroup.class})
    private String userId;

    @NotEmpty(message = "用戶名不能為空")  //不會自動去掉前后空格
    private String userName;

    //有多個條件時，如果都不滿足，會打印所有信息
    @NotBlank(message = "用戶密碼不能為空")  //會自動去掉字符串中的空格
    @Length(min = 6, max = 20, message = "密碼不能少於6位，多於20位")
    private String password;

    @Email(message = "必須為有效郵箱")  //為空時不會報錯
    @NotNull
    private String email;

    @Pattern(regexp = "^[1][3,4,5,6,7,8,9][0-9]{9}$", message = "手機號格式有誤")
    private String phone;

    @Min(value = 18, message = "年齡必須大於18歲")
    @Max(value = 68, message = "年齡必須小於68歲") //為空時不會報錯
    private Integer age;

    @Past(message = "時間不能是未來的時間") //為空時不會報錯
    private Date birthday;

    @Size(min = 1, message = "不能少於1個好友") //為空時不會報錯
    private List<UserInfo>friends;

    @GenderValue(message = "性別輸入不合法", genders = {"男","女"})
    private String gender;

    public String getGender() {
        return gender;
    }

    public void setGender(String gender) {
        this.gender = gender;
    }

    public String getUserId() {
        return userId;
    }

    public void setUserId(String userId) {
        this.userId = userId;
    }

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone;
    }

    public Date getBirthday() {
        return birthday;
    }

    public void setBirthday(Date birthday) {
        this.birthday = birthday;
    }

    public List<UserInfo> getFriends() {
        return friends;
    }

    public void setFriends(List<UserInfo> friends) {
        this.friends = friends;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    @Override
    public String toString() {
        return "UserInfo{" +
                "userId='" + userId + '\'' +
                ", userName='" + userName + '\'' +
                ", password='" + password + '\'' +
                ", email='" + email + '\'' +
                ", phone='" + phone + '\'' +
                ", age=" + age +
                ", birthday=" + birthday +
                ", friends=" + friends +
                '}';
    }
}

4.3 分組

public interface InsertGroup {
}

 

public interface UpdateGroup {
}

注意：分組校驗的時候，必須要用Hibernate提供的@Valided注解。

4.4 非全局異常處理

一般我們會在controller進行傳參校驗，校驗不通過的時候會拋出異常，需要對異常信息進行有效的提取，並返回給前端。先看一種非全局的處理方法：

@RestController
public class UserController {

    @Autowired
    UserInfoService userInfoService;

    @RequestMapping("/register")
    public CommonRes register(@Valid UserInfo userInfo, BindingResult bindingResult){
        userInfoService.register(userInfo);
        if(bindingResult.hasErrors()){
            Map<String, String> map = new HashMap<>();
            bindingResult.getFieldErrors().forEach((item) -> {
                String message = item.getDefaultMessage();
                String filed = item.getField();
                map.put(filed, message);
            });
            return CommonRes.fail(map.toString());
        }
        return CommonRes.success(null);
    }

    @RequestMapping("/update")
    public CommonRes updateUserInfo(@Valid UserInfo userInfo, BindingResult bindingResult){
        userInfoService.update(userInfo);
        if(bindingResult.hasErrors()){
            return CommonRes.fail(bindingResult.getAllErrors().toString());
        }
        return CommonRes.success(null);
    }
}

優點：較為靈活

缺點：每次校驗都需要寫一遍bindingResult的處理代碼，比較繁瑣

4.5 全局異常處理

結合Spring中的全局異常處理方案，我們可以對校驗出來的結果進行全局處理。

異常處理類：

@ControllerAdvice
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(value = {MethodArgumentNotValidException.class, BindException.class})
    public CommonRes handleValidException(Exception e) {
        BindingResult bindingResult = null;

        if(e instanceof MethodArgumentNotValidException) {
            bindingResult = ((MethodArgumentNotValidException)e).getBindingResult();
        } else if (e instanceof BindException) {
            bindingResult = ((BindException)e).getBindingResult();
        }

        Map<String, String>errorMap = new HashMap<>(16);
        assert bindingResult != null;
        bindingResult.getFieldErrors().forEach(fieldError -> errorMap.put(fieldError.getField(), fieldError.getDefaultMessage()));
        return CommonRes.fail(errorMap.toString());
    }
}

將Controller層代碼改為

@RestController
public class UserController {

    @Autowired
    UserInfoService userInfoService;

    @RequestMapping("/register")
    public CommonRes register(UserInfo userInfo){
        userInfoService.register(userInfo);
        // if(bindingResult.hasErrors()){
        //     Map<String, String> map = new HashMap<>();
        //     bindingResult.getFieldErrors().forEach((item) -> {
        //         String message = item.getDefaultMessage();
        //         String filed = item.getField();
        //         map.put(filed, message);
        //     });
        //     return CommonRes.fail(map.toString());
        // }
        return CommonRes.success(null);
    }

    @RequestMapping("/update")
    public CommonRes updateUserInfo(UserInfo userInfo){
        userInfoService.update(userInfo);
        // if(bindingResult.hasErrors()){
        //     return CommonRes.fail(bindingResult.getAllErrors().toString());
        // }
        return CommonRes.success(null);
    }
}

優點：簡化了編程，注釋掉的代碼就可以去掉了。

缺點：某些情況下不夠靈活，比如不同參數的校驗需要返回不同的狀態碼時，粗糙的全局處理就無法滿足需求了。

但是一般來說，參數錯誤異常會使用統一的狀態碼，所以這種寫法已經可以滿足大多數人的校驗需求了。

4.7 自定義注解

有時候現有的注解可能不能滿足我們的需求，這個時候就用到自定義的注解了。

例如現在想要對gender字段進行校驗，只能為“男”，或者為“女”。可以這么做

• 定義注解

@Documented
@Constraint(validatedBy = {GenderValueConstraintValidator.class}) //交給哪個類校驗
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface GenderValue {
    String message() default "";

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

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

    String[] genders()default {};
}

• 校驗類

public class GenderValueConstraintValidator implements ConstraintValidator<GenderValue, String> {

    private Set<String> set = new HashSet<>();

    @Override
    public void initialize(GenderValue constraintAnnotation) {
        String[]genders = constraintAnnotation.genders();
        for (String gender : genders) {
            set.add(gender);
        }
    }

    //校驗的結果由這個類決定
    @Override
    public boolean isValid(String value, ConstraintValidatorContext constraintValidatorContext) {
        return set.contains(value);
    }
}

• 使用方法

    @GenderValue(message = "性別輸入不合法", genders = {"男","女"})
    private String gender;

 

4.8、參數校驗放在controller層還是service層？

自從看到一個大神把所有的參數校驗放在service層，我就有點懷疑人生了。參數校驗究竟是放在哪一層呢？

花了點時間特地去查了下，最后得出的結論是：

controller層和service層都需要做校驗，但是側重點不同。

controller層偏向於參數形式上的合法性，與業務無關，比如這個字段是否能為空，郵箱格式是否正確，手機格式是否正確等等。

service層偏向於校驗邏輯上的合法性，比如這個同名的用戶是否已經存在，比如這個郵箱是不是已經被其他用戶注冊了等等。

 

4.9、其他方法

之前看到一種校驗方式，將處理結果進行一定的封裝，使用起來也比較方便：

• 定義ValidationResult存放校驗結果

/**
 * @author peng
 */
public class ValidationResult {

    /**
     * 結果校驗是否有錯
     */
    private boolean hasErrors;

    /**
     * 存放錯誤信息
     */
    private Map<String,String>errorMsgMap = new HashMap<>();

    public boolean isHasErrors() {
        return hasErrors;
    }

    public void setHasErrors(boolean hasErrors) {
        this.hasErrors = hasErrors;
    }

    public Map<String, String> getErrorMsgMap() {
        return errorMsgMap;
    }

    public void setErrorMsgMap(Map<String, String> errorMsgMap) {
        this.errorMsgMap = errorMsgMap;
    }

    /**
     * 實現通用的格式化字符串信息獲取錯誤結果的msg方法。
     * @return 錯誤參數
     */
    public String getErrMsg(){
        return StringUtils.join(errorMsgMap.values().toArray(), ",");
    }
}

• 校驗類

/**
 * @author peng
 */
@Component
public class ValidatorImpl implements InitializingBean {

    private Validator validator;

    /**
     * 實現校驗方法並返回校驗結果
     */
    public ValidationResult validate(Object bean){
        ValidationResult result = new ValidationResult();
        Set<ConstraintViolation<Object>> constraintViolationSet = validator.validate(bean);
        if(constraintViolationSet.size() > 0 ){
            result.setHasErrors(true);
            constraintViolationSet.forEach(constraintViolation->{
                String errMsg = constraintViolation.getMessage();
                String propertyName = constraintViolation.getPropertyPath().toString();
                result.getErrorMsgMap().put(propertyName, errMsg);
            });
        }
        return result;
    }

    @Override
    public void afterPropertiesSet() throws Exception {
        //將hibernate validator通過工廠的初始化方式使其實例化
        this.validator = Validation.buildDefaultValidatorFactory().getValidator();
    }
}

• 使用方法

注入驗證類、返回結果

@Service
public class UserServiceImpl implements UserService, UserDetailsService {

    @Autowired
    UserDOMapper userDOMapper;

    @Autowired
    ValidatorImpl validator;

/**
     *
     * @param userModel 用戶信息
     * @return 0 失敗，大於0 成功
     * @throws BusinessException 管理員無法刪除
     */
    @Override
    public int registerUser(UserModel userModel) throws BusinessException {
        ValidationResult validate = validator.validate(userModel);
        if(validate.isHasErrors()){
            throw new BusinessException(EmBusinessError.PARAMETER_VALIDATION_ERROR, validate.getErrMsg());
        }
        UserDO userDO = userDOMapper.selectByLoginName(userModel.getLoginName());
        if(userDO != null){
            throw new BusinessException(EmBusinessError.USER_IS_EXIST);
        }

        return userDOMapper.insertSelective(convertFromModel(userModel));
    }

  private UserDO convertFromModel(UserModel userModel){
        if(userModel == null){
            return null;
        }
        UserDO userDO = new UserDO();
        BeanUtils.copyProperties(userModel, userDO);
        return userDO;
    }

    private UserModel convertFromDO(UserDO userDO){
        if(userDO == null){
            return null;
        }

        UserModel userModel = new UserModel();
        BeanUtils.copyProperties(userDO, userModel);

        if(userDO.getUserId() != null){
            List<RightModel> rightModelList = permissionService.getRightListByUserId(userDO.getUserId());
            userModel.setRightModelList(rightModelList);
        }
        return userModel;
    }

    private List<UserModel> convertFromDOList(List<UserDO>userDOList){
        if(userDOList == null){
            return null;
        }
        return userDOList.stream().map(this::convertFromDO).collect(Collectors.toList());
    }


}

優缺點：算是一種比較這種的方案，可以自定義錯誤類型，使用起來也比較方便。

不過個人還是傾向於4.5的做法，已經可以滿足大部分項目的需求了。

 

如有錯誤，歡迎批評指正！