如何在 Spring/Spring Boot 中作參數校驗？你須要瞭解的都在這裏！

時間 2019-11-11

標籤如何 spring boot 參數校驗須要瞭解都在這裏欄目 Spring 简体版

原文原文鏈接

本文爲做者原創，如需轉載請在文首著名地址，公衆號轉載請申請開白。前端

springboot-guide : 適合新手入門以及有經驗的開發人員查閱的 Spring Boot 教程（業餘時間維護中，歡迎一塊兒維護）。java

數據的校驗的重要性就不用說了，即便在前端對數據進行校驗的狀況下，咱們仍是要對傳入後端的數據再進行一遍校驗，避免用戶繞過瀏覽器直接經過一些 HTTP 工具直接向後端請求一些違法數據。git

本文結合本身在項目中的實際使用經驗，能夠說文章介紹的內容很實用，不瞭解的朋友能夠學習一下，後面能夠立馬實踐到項目上去。github

下面我會經過實例程序演示如何在 Java 程序中尤爲是 Spring 程序中優雅地的進行參數驗證。web

基礎設施搭建

實體類

下面這個是示例用到的實體類。spring

@Data
@AllArgsConstructor
@NoArgsConstructor
public class Person {

    @NotNull(message = "classId 不能爲空")
    private String classId;

    @Size(max = 33)
    @NotNull(message = "name 不能爲空")
    private String name;

    @Pattern(regexp = "((^Man$|^Woman$|^UGM$))", message = "sex 值不在可選範圍")
    @NotNull(message = "sex 不能爲空")
    private String sex;

    @Email(message = "email 格式不正確")
    @NotNull(message = "email 不能爲空")
    private String email;

}

正則表達式說明：數據庫

- ^string : 匹配以 string 開頭的字符串
- string$ ：匹配以 string 結尾的字符串
- ^string$ ：精確匹配 string 字符串
- ((^Man$|^Woman$|^UGM$)) : 值只能在 Man,Woman,UGM 這三個值中選擇

下面這部分校驗註解說明內容參考自：https://www.cnkirito.moe/spring-validation/ ，感謝@徐靖峯。編程

JSR提供的校驗註解:

@Null 被註釋的元素必須爲 null
@NotNull 被註釋的元素必須不爲 null
@AssertTrue 被註釋的元素必須爲 true
@AssertFalse 被註釋的元素必須爲 false
@Min(value) 被註釋的元素必須是一個數字，其值必須大於等於指定的最小值
@Max(value) 被註釋的元素必須是一個數字，其值必須小於等於指定的最大值
@DecimalMin(value) 被註釋的元素必須是一個數字，其值必須大於等於指定的最小值
@DecimalMax(value) 被註釋的元素必須是一個數字，其值必須小於等於指定的最大值
@Size(max=, min=) 被註釋的元素的大小必須在指定的範圍內
@Digits (integer, fraction) 被註釋的元素必須是一個數字，其值必須在可接受的範圍內
@Past 被註釋的元素必須是一個過去的日期
@Future 被註釋的元素必須是一個未來的日期
@Pattern(regex=,flag=) 被註釋的元素必須符合指定的正則表達式

Hibernate Validator提供的校驗註解：

@NotBlank(message =) 驗證字符串非null，且長度必須大於0
@Email 被註釋的元素必須是電子郵箱地址
@Length(min=,max=) 被註釋的字符串的大小必須在指定的範圍內
@NotEmpty 被註釋的字符串的必須非空
@Range(min=,max=,message=) 被註釋的元素必須在合適的範圍內

驗證Controller的輸入

驗證請求體(RequestBody)

Controller：

咱們在須要驗證的參數上加上了@Valid註解，若是驗證失敗，它將拋出MethodArgumentNotValidException。默認狀況下，Spring會將此異常轉換爲HTTP Status 400（錯誤請求）。

@RestController
@RequestMapping("/api")
public class PersonController {

    @PostMapping("/person")
    public ResponseEntity<Person> getPerson(@RequestBody @Valid Person person) {
        return ResponseEntity.ok().body(person);
    }
}

ExceptionHandler：

自定義異常處理器能夠幫助咱們捕獲異常，並進行一些簡單的處理。若是對於下面的處理異常的代碼不太理解的話，能夠查看這篇文章《SpringBoot 處理異常的幾種常見姿式》。

@ControllerAdvice(assignableTypes = {PersonController.class})
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidationExceptions(
            MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getAllErrors().forEach((error) -> {
            String fieldName = ((FieldError) error).getField();
            String errorMessage = error.getDefaultMessage();
            errors.put(fieldName, errorMessage);
        });
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(errors);
    }
}

經過測試驗證：

下面我經過 MockMvc 模擬請求 Controller 的方式來驗證是否生效，固然你也能夠經過 Postman 這種工具來驗證。

咱們試一下全部參數輸入正確的狀況。

@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureMockMvc
public class PersonControllerTest {
    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private ObjectMapper objectMapper;

    @Test
    public void should_get_person_correctly() throws Exception {
        Person person = new Person();
        person.setName("SnailClimb");
        person.setSex("Man");
        person.setClassId("82938390");
        person.setEmail("Snailclimb@qq.com");

        mockMvc.perform(post("/api/person")
                .contentType(MediaType.APPLICATION_JSON_UTF8)
                .content(objectMapper.writeValueAsString(person)))
                .andExpect(MockMvcResultMatchers.jsonPath("name").value("SnailClimb"))
                .andExpect(MockMvcResultMatchers.jsonPath("classId").value("82938390"))
                .andExpect(MockMvcResultMatchers.jsonPath("sex").value("Man"))
                .andExpect(MockMvcResultMatchers.jsonPath("email").value("Snailclimb@qq.com"));
    }
}

驗證出現參數不合法的狀況拋出異常而且能夠正確被捕獲。

@Test
    public void should_check_person_value() throws Exception {
        Person person = new Person();
        person.setSex("Man22");
        person.setClassId("82938390");
        person.setEmail("SnailClimb");

        mockMvc.perform(post("/api/person")
                .contentType(MediaType.APPLICATION_JSON_UTF8)
                .content(objectMapper.writeValueAsString(person)))
                .andExpect(MockMvcResultMatchers.jsonPath("sex").value("sex 值不在可選範圍"))
                .andExpect(MockMvcResultMatchers.jsonPath("name").value("name 不能爲空"))
                .andExpect(MockMvcResultMatchers.jsonPath("email").value("email 格式不正確"));
    }

使用 Postman 驗證結果以下：

驗證請求參數(Path Variables 和 Request Parameters)

Controller：

必定必定不要忘記在類上加上 Validated 註解了，這個參數能夠告訴 Spring 去校驗方法參數。

@RestController
@RequestMapping("/api")
@Validated
public class PersonController {

    @GetMapping("/person/{id}")
    public ResponseEntity<Integer> getPersonByID(@Valid @PathVariable("id") @Max(value = 5,message = "超過 id 的範圍了") Integer id) {
        return ResponseEntity.ok().body(id);
    }

    @PutMapping("/person")
    public ResponseEntity<String> getPersonByName(@Valid @RequestParam("name") @Size(max = 6,message = "超過 name 的範圍了") String name) {
        return ResponseEntity.ok().body(name);
    }
}

ExceptionHandler：

@ExceptionHandler(ConstraintViolationException.class)
    ResponseEntity<String> handleConstraintViolationException(ConstraintViolationException e) {
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(e.getMessage());
    }

經過測試驗證：

@Test
    public void should_check_param_value() throws Exception {

        mockMvc.perform(get("/api/person/6")
                .contentType(MediaType.APPLICATION_JSON_UTF8))
                .andExpect(status().isBadRequest())
                .andExpect(content().string("getPersonByID.id: 超過 id 的範圍了"));
    }

    @Test
    public void should_check_param_value2() throws Exception {

        mockMvc.perform(put("/api/person")
                .param("name","snailclimbsnailclimb")
                .contentType(MediaType.APPLICATION_JSON_UTF8))
                .andExpect(status().isBadRequest())
                .andExpect(content().string("getPersonByName.name: 超過 name 的範圍了"));
    }

驗證 Service 中的方法

咱們還能夠驗證任何Spring組件的輸入，而不是驗證控制器級別的輸入，咱們可使用@Validated和@Valid註釋的組合來實現這一需求。

必定必定不要忘記在類上加上 Validated 註解了，這個參數能夠告訴 Spring 去校驗方法參數。

@Service
@Validated
public class PersonService {

    public void validatePerson(@Valid Person person){
        // do something
    }
}

經過測試驗證：

@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureMockMvc
public class PersonServiceTest {
    @Autowired
    private PersonService service;

    @Test(expected = ConstraintViolationException.class)
    public void should_throw_exception_when_person_is_not_valid() {
        Person person = new Person();
        person.setSex("Man22");
        person.setClassId("82938390");
        person.setEmail("SnailClimb");
        service.validatePerson(person);
    }

}

Validator 編程方式手動進行參數驗證

某些場景下可能會須要咱們手動校驗並得到校驗結果。

@Test
    public void check_person_manually() {

        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
        Validator validator = factory.getValidator();
        Person person = new Person();
        person.setSex("Man22");
        person.setClassId("82938390");
        person.setEmail("SnailClimb");
        Set<ConstraintViolation<Person>> violations = validator.validate(person);
        //output:
        //email 格式不正確
        //name 不能爲空
        //sex 值不在可選範圍
        for (ConstraintViolation<Person> constraintViolation : violations) {
            System.out.println(constraintViolation.getMessage());
        }
    }

上面咱們是經過 Validator 工廠類得到的 Validator 示例，固然你也能夠經過 @Autowired 直接注入的方式。可是在非 Spring Component 類中使用這種方式的話，只能經過工廠類來得到 Validator。

@Autowired
Validator validate

自定以 Validator(實用)

若是自帶的校驗註解沒法知足你的需求的話，你還能夠自定義實現註解。

案例一:校驗特定字段的值是否在可選範圍

好比咱們如今多了這樣一個需求：Person類多了一個 region 字段，region 字段只能是China、China-Taiwan、China-HongKong這三個中的一個。

第一步你須要建立一個註解：

@Target({FIELD})
@Retention(RUNTIME)
@Constraint(validatedBy = RegionValidator.class)
@Documented
public @interface Region {

    String message() default "Region 值不在可選範圍內";

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

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

第二步你須要實現 ConstraintValidator接口，並重寫isValid 方法：

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
import java.util.HashSet;

public class RegionValidator implements ConstraintValidator<Region, String> {

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        HashSet<Object> regions = new HashSet<>();
        regions.add("China");
        regions.add("China-Taiwan");
        regions.add("China-HongKong");
        return regions.contains(value);
    }
}

如今你就可使用這個註解：

@Region
    private String region;

案例二:校驗電話號碼

校驗咱們的電話號碼是否合法，這個能夠經過正則表達式來作，相關的正則表達式均可以在網上搜到，你甚至能夠搜索到針對特定運營商電話號碼段的正則表達式。

PhoneNumber.java

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

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.PARAMETER;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

@Documented
@Constraint(validatedBy = PhoneNumberValidator.class)
@Target({FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface PhoneNumber {
    String message() default "Invalid phone number";
    Class[] groups() default {};
    Class[] payload() default {};
}

PhoneNumberValidator.java

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;

public class PhoneNumberValidator implements ConstraintValidator<PhoneNumber,String> {

    @Override
    public boolean isValid(String phoneField, ConstraintValidatorContext context) {
        if (phoneField == null) {
            // can be null
            return true;
        }
        return phoneField.matches("^1(3[0-9]|4[57]|5[0-35-9]|8[0-9]|70)\\d{8}$") && phoneField.length() > 8 && phoneField.length() < 14;
    }
}

搞定，咱們如今就可使用這個註解了。

@PhoneNumber(message = "phoneNumber 格式不正確")
@NotNull(message = "phoneNumber 不能爲空")
private String phoneNumber;

使用驗證組

某些場景下咱們須要使用到驗證組，這樣說可能不太清楚，說簡單點就是對對象操做的不一樣方法有不一樣的驗證規則，示例以下（這個就我目前經歷的項目來講使用的比較少，由於自己這個在代碼層面理解起來是比較麻煩的，而後寫起來也比較麻煩）。

先建立兩個接口：

public interface AddPersonGroup {
}
public interface DeletePersonGroup {
}

咱們能夠這樣去使用驗證組

@NotNull(groups = DeletePersonGroup.class)
@Null(groups = AddPersonGroup.class)
private String group;

@Service
@Validated
public class PersonService {

    public void validatePerson(@Valid Person person) {
        // do something
    }

    @Validated(AddPersonGroup.class)
    public void validatePersonGroupForAdd(@Valid Person person) {
        // do something
    }

    @Validated(DeletePersonGroup.class)
    public void validatePersonGroupForDelete(@Valid Person person) {
        // do something
    }

}

經過測試驗證：

@Test(expected = ConstraintViolationException.class)
    public void should_check_person_with_groups() {
        Person person = new Person();
        person.setSex("Man22");
        person.setClassId("82938390");
        person.setEmail("SnailClimb");
        person.setGroup("group1");
        service.validatePersonGroupForAdd(person);
    }

    @Test(expected = ConstraintViolationException.class)
    public void should_check_person_with_groups2() {
        Person person = new Person();
        person.setSex("Man22");
        person.setClassId("82938390");
        person.setEmail("SnailClimb");
        service.validatePersonGroupForDelete(person);
    }

使用驗證組這種方式的時候必定要當心，這是一種反模式，還會形成代碼邏輯性變差。

代碼地址：https://github.com/Snailclimb/springboot-guide/tree/master/source-code/advanced/bean-validation-demo