SpringBoot 使用 Hibernate-Validator 优雅校验参数

在接口服务中,会有各种各样的入参,我们不可能完全不做任何校验就直接进入到业务处理的环节,通常会有一个基础的数据验证的机制,待这些验证过程完毕,结果无误后,参数才会进入到正式的业务处理中。

而数据验证又分为两种,一种是无业务关联的规则性验证,一种是根据现有数据进行的联动性数据验证。而 Hibernate-Validator 则适合做无业务关联的规则性验证,而这类验证的代码大多是可复用的。

一、基本使用

1、首先需要导入 maven 依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.1.5.Final</version>
</dependency>

2、添加一个普通的 Get 接口,参数 name 的长度需要在 1~10 之间,参数 age 的最小值为 0。

import org.springframework.validation.annotation.Validated;
import javax.validation.constraints.Min;
import javax.validation.constraints.Size;

@RestController
@Validated
public class UserController {

    @GetMapping("/validate1")
    public String validate1(@Size(min = 1, max = 10, message = "姓名长度必须为1到10") @RequestParam("name") String name,
                            @Min(value = 0, message = "年龄须大于0") @RequestParam("age") Integer age) {
        return "validate1";
    }
}

注意,Get 请求时,类名需要加注解 @Validated 才能对参数进行校验。当校验失败时,会抛出 ConstraintViolationException 异常。

3、添加 Post 接口。首先给 Model 类增加校验注解。

@Data
public class LoginVo {

    @Length(min = 5, max = 17, message = "userName长度须在[5,17]") // 可以为 null,若不为 null,则长度为 [5, 17]
    private String userName;

    // @Size不能验证Integer,适用于String
    @Size(min = 1, max = 3, message = "password长度须在[1,3]")
    private String password;

    @Size(min = 1,max = 5,message = "list的Size在[1,5]") // list 可以为 null,若不为 null,则长度为 [1, 5]
    private List<String> list;

    @NotNull
    @Valid // 级联校验,该注解将会校验自定义类
    private OrderItem detailInfo;
}
@Data
class DetailInfo {

    @NotEmpty(message = "name不能为空")
    private String name;

    @Pattern(regexp="^\\d+$", message = "itemCode需要数字") // 匹配任何数字
    private String itemCode;

    @Range(min = 10, max = 100, message = "range在[10,100]之间")
    private int age;
}

在控制器中增加一个 POST 请求接口。

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

    @GetMapping("/validate1")
    public String validate1(@Size(min = 1, max = 10, message = "姓名长度须为1到10") @RequestParam("name") String name) {
        return "validate1";
    }

    @PostMapping("/validate2")
    public String validate2(@Valid @RequestBody LoginVo loginVo) {
        System.out.println(loginVo);
        return "validate2";
    }
}

发起一个 POST 请求:

POST http://localhost:8080/user/validate2
Content-Type: application/json

{
  "userName": "Tom",
  "password": "1234",
  "list": [1,2,3],
  "detailInfo": {
    "name": "Tom",
    "itemCode": "510000",
    "age": 120
  }
}

服务器返回 400 的状态码。password的尺寸需在[1,3]之间 userName长度需在[5,17]之间 range在[10,100]之间 。

二、校验模式

上面例子中一次性返回了所有验证不通过的集合,通常按顺序验证到第一个字段不符合验证要求时,就可以直接拒绝请求了。Hibernate Validator有以下两种验证模式:

  1. 普通模式(默认是这个模式)
    普通模式时,会校验完所有的属性,然后返回所有的验证失败信息。
  1. 快速失败返回模式
    快速失败时,只要有一个验证失败,则返回该失败信息。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import javax.validation.Validation;
import javax.validation.Validator;
import javax.validation.ValidatorFactory;

@Configuration
public class ValidatorConfiguration {
    @Bean
    public Validator validator() {
        ValidatorFactory validatorFactory = Validation.byProvider(HibernateValidator.class).configure().failFast(true).buildValidatorFactory();
        return validatorFactory.getValidator();
    }
}

其中 failFast:true 快速失败返回模式;false 普通模式。

三、统一处理 Controller 层异常

当校验失败时,会抛出 MethodArgumentNotValidException 异常,但是我们不应该在 Controller 层处理异常,Controller 层不应该有过多的逻辑处理,异常也不用每个 Controller 都来处理一遍,因此需要全局捕获异常,统一处理。

import org.springframework.http.HttpStatus;
import org.springframework.util.CollectionUtils;
import org.springframework.validation.ObjectError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.ResponseStatus;

import javax.validation.ConstraintViolation;
import javax.validation.ConstraintViolationException;
/**
 * 统一异常处理类
 */
@ControllerAdvice
public class GlobalExceptionHandler {

    /**
     * 统一捕获处理ConstraintViolationException异常
     */
    @ExceptionHandler(ConstraintViolationException.class)
    @ResponseBody
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public String resolveConstraintViolationException(ConstraintViolationException ex) {
        Set<ConstraintViolation<?>> constraintViolations = ex.getConstraintViolations();
        StringBuilder msgBuilder = new StringBuilder();
        if (!CollectionUtils.isEmpty(constraintViolations)) {
            for (ConstraintViolation constraintViolation : constraintViolations) {
                String msg = constraintViolation.getMessage();
                msgBuilder.append(msg).append(",");
            }
        }
        return msgBuilder.toString();
    }

    /**
     * 统一捕获处理MethodArgumentNotValidException异常
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseBody
    @ResponseStatus(HttpStatus.OK)
    public String resolveMethodArgumentNotValidException(MethodArgumentNotValidException ex) {
        List<ObjectError> objectErrors = ex.getBindingResult().getAllErrors();
        StringBuilder msgBuilder = new StringBuilder();
        if (!CollectionUtils.isEmpty(objectErrors)) {
            for (ObjectError objectError : objectErrors) {
                String msg = objectError.getDefaultMessage();
                msgBuilder.append(msg).append(" ");
            }
        }
        return msgBuilder.toString();
    }
}

在这里,统一处理了 ConstraintViolationException 和 MethodArgumentNotValidException 这两个异常。

在处理异常时,返回状态码通过 @ResponseStatus 定义。例如抛出 ConstraintViolationException 异常时,前端得到的状态码为 400,而抛出 MethodArgumentNotValidException 异常时,前端的状态码为 200。这都需要根据实际业务情况决定。

此外,方法的返回正也需要根据业务逻辑返回对应的值。

四、自定义校验器参数校验

除了默认提供的校验注解外,我们可以定义自己的校验注解,默认的注解总有不满足要求的时候。

例如需要一个校验性别的注解,要求传递一个只能时 man 或者 female 的字符串。

首先创建约束注解类。

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

@Target({ElementType.FIELD})
@Documented
@Constraint(validatedBy = {GenderValidator.class})
public @interface Gender {
    // 验证失败时显示的信息
    String message() default "gender error";
    // 分组的内容
    Class<?>[] groups() default { };
    // 错误验证的级别
    Class<? extends Payload>[] payload() default {};
}

使用 @interface 定义注解时,意味着它实现了 java.lang.annotation.Annotation 接口,即该注解就是一个Annotation。定义 Annotation 时,@interface 是必须的。

使用 @Documented 修饰该 Annotation,则表示它可以出现在 javadoc 中。定义 Annotation 时,@Documented 可有可无;若没有定义,则 Annotation 不会出现在 javadoc 中。

@Constraint(validatedBy = { GenderValidator.class})用来指定处理这个注解逻辑的类。

@Target 的作用,就是来指定 Annotation 的类型属性。@Target(ElementType.FIELD) 的意思就是指定该 Annotation 的类型是用来修饰“字段(包括枚举常量)”的注解。定义 Annotation 时,@Target 可有可无。若有 @Target,则该 Annotation 只能用于它所指定的地方;若没有 @Target,则该 Annotation 可以用于任何地方。其中,ElementType 可选的类型如下:

  • TYPE 意味着,它能标注"类、接口(包括注释类型)或枚举声明"。
  • FIELD 意味着,它能标注"字段声明"。
  • METHOD 意味着,它能标注"方法"。
  • PARAMETER 意味着,它能标注"参数"。
  • CONSTRUCTOR 意味着,它能标注"构造方法"。
  • LOCAL_VARIABLE 意味着,它能标注"局部变量"。

属性 message 用于显示错误信息,这个字段是必须的,groups 和 payload 也是必须的。

该注解的实现类如下。

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

public class GenderValidator implements ConstraintValidator<Gender, String> {

    private Gender gender;

    @Override
    public void initialize(Gender constraintAnnotation) {
        this.gender = constraintAnnotation;
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        return value.equals("man") || value.equals("female");
    }
}

注意需要实现 ConstraintValidator 接口,泛型的第一个参数是注解类(Gender),第二个参数是注解修饰属性的类型,这里需要修饰的是 String gender;,所以是 String。

使用如下:

@Data
public class LoginVo {

    @Length(min = 5, max = 17, message = "userName长度需在[5,17]之间")
    private String userName;

    @Size(min = 1, max = 3, message = "password的尺寸需在[1,3]之间")
    private String password;

    @Gender
    private String gender;
}

发一个 POST 请求:

POST http://localhost:8090/user/validate2
Content-Type: application/json

{
  "userName": "Tomas",
  "password": "1234",
  "gender": "unknow"
}

由于 gender 的内容不是我们定义的 man 或者 female,不符合校验规则,所以返回了错误信息 gender error 。

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 151,829评论 1 331
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 64,603评论 1 273
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 101,846评论 0 226
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 42,600评论 0 191
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 50,780评论 3 272
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 39,695评论 1 192
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 31,136评论 2 293
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 29,862评论 0 182
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 33,453评论 0 229
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 29,942评论 2 233
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 31,347评论 1 242
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 27,790评论 2 236
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 32,293评论 3 221
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 25,839评论 0 8
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,448评论 0 181
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 34,564评论 2 249
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 34,623评论 2 249