如何在 Spring/Spring Boot 中作参数校验？你须要了解的都在这里！

时间  2019-11-11
标签 如何 spring boot 参数 校验 须要 了解 都在 这里 栏目 Spring 繁體版
原文   原文链接

本文为做者原创，如需转载请在文首著名地址，公众号转载请申请开白。前端

springboot-guide : 适合新手入门以及有经验的开发人员查阅的 Spring Boot 教程（业余时间维护中，欢迎一块儿维护）。java

数据的校验的重要性就不用说了，即便在前端对数据进行校验的状况下，咱们仍是要对传入后端的数据再进行一遍校验，避免用户绕过浏览器直接经过一些 HTTP 工具直接向后端请求一些违法数据。git

本文结合本身在项目中的实际使用经验，能够说文章介绍的内容很实用，不了解的朋友能够学习一下，后面能够立马实践到项目上去。github

下面我会经过实例程序演示如何在 Java 程序中尤为是 Spring 程序中优雅地的进行参数验证。web

基础设施搭建

相关依赖

若是开发普通 Java 程序的的话，你须要可能须要像下面这样依赖：面试

<dependency>
            <groupId>org.hibernate.validator</groupId>
            <artifactId>hibernate-validator</artifactId>
            <version>6.0.9.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>

使用 Spring Boot 程序的话只须要spring-boot-starter-web 就够了，它的子依赖包含了咱们所须要的东西。除了这个依赖，下面的演示还用到了 lombok ，因此不要忘记添加上相关依赖。正则表达式

<dependencies>
        <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>
        </dependency>
    </dependencies>

实体类

下面这个是示例用到的实体类。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 验证结果以下：

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

@NotNull vs @Column(nullable = false)(重要)

在使用 JPA 操做数据的时候会常常碰到 @Column(nullable = false) 这种类型的约束，那么它和 @NotNull 有何区别呢？搞清楚这个仍是很重要的！

  • @NotNull是 JSR 303 Bean验证批注,它与数据库约束自己无关。
  • @Column(nullable = false) : 是JPA声明列为非空的方法。

总结来讲就是即前者用于验证，然后者则用于指示数据库建立表的时候对表的约束。

TODO

  • [ ] 原理分析

参考

公众号

若是你们想要实时关注我更新的文章以及分享的干货的话，能够关注个人公众号。

《Java面试突击》: 由本文档衍生的专为面试而生的《Java面试突击》V2.0 PDF 版本公众号后台回复 "Java面试突击" 便可免费领取！

Java工程师必备学习资源: 一些Java工程师经常使用学习资源公众号后台回复关键字 “1” 便可免费无套路获取。

个人公众号

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程