SpringBoot 如何自定义请求参数校验

• 一、bean validation基本概念
• • 3.2 自定义validator

最近在工作中遇到写一些api，这些api的请求参数非常多，嵌套也非常复杂，如果参数的校验代码全部都手动去实现，写起来真的非常痛苦。

正好spring*里面有一个validation，这里记录一下怎么使用，以及怎么自定义它的返回结果。

一、bean validation基本概念

bean validation是java中的一项标准，它通过一些注解表达了对实体的限制规则。通过提出了一些api和扩展性的规范，这个规范是没有提供具体实现的，希望能够constrain once, validate everywhere。现在它已经发展到了2.0，兼容java8。

hibernate validation实现了bean validation标准，里面还增加了一些注解，在程序中引入它我们就可以直接使用。

spring mvc也支持bean validation，它对hibernate validation进行了二次封装，添加了自动校验，并将校验信息封装进了特定的bindingresult类中，在springboot中我们可以添加implementation(‘org.springframework.boot:spring-boot-starter-validation')引入这个库，实现对bean的校验功能。

二、基本用法

gradle dependencies如下：

dependencies {
    implementation('org.springframework.boot:spring-boot-starter-validation')
    implementation('org.springframework.boot:spring-boot-starter-web')
}

定义一个示例的bean，例如下面的user.java。

public class user {
    @notblank
    @size(max=10)
    private string name;
    private string password;
    public string getname() {
        return name;
    }
    public void setname(string name) {
        this.name = name;
    }
    public string getpassword() {
        return password;
    }
    public void setpassword(string password) {
        this.password = password;
    }
}

在name属性上，添加@notblank和@size(max=10)的注解，表示user对象的name属性不能为字符串且长度不能超过10个字符。

然后我们暂时不添加任何多余的代码，直接写一个usercontroller对外提供一个restful的get接口，注意接口的参数用到了@validated注解。

// usercontroller.java，省略其他代码
@restcontroller
public class usercontroller {
    @requestmapping(value = "/validation/get", method = requestmethod.get)
    public serviceresponse validateget(@validated user user) {
        serviceresponse serviceresponse = new serviceresponse();
        serviceresponse.setcode(0);
        serviceresponse.setmessage("test");
        return serviceresponse;
    }
}
// serviceresponse.java，简单包含了code、message字段返回结果。
public class serviceresponse {
    private int code;
    private string message;
    ... 省略getter、setter ...
}

启动springboot程序，发一个测试请求看一下：

http://127.0.0.1:8080/validation/get?name=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&password=1

此时已经可以实现参数的校验了，但是返回的结果不太友好，下面看一下怎么定制返回的消息。在定制返回结果前，先看下一下内置的校验注解有哪些，在这里我不一个个去贴了，写代码的时候根据需要进入到源码里面去看即可。

早期spring版本中，都是在controller的方法中添加errors/bindingresult参数，由spring注入errors/bindingresult对象，再在controller中手写校验逻辑实现校验。

新版本提供注解的方式（controller上面bean加一个@validated注解），将校验逻辑和controller分离。

三、自定义校验

3.1 自定义注解

显然除了自带的notnull、notblank、size等注解，实际业务上还会需要特定的校验规则。

假设我们有一个参数address，必须以beijing开头，那我们可以定义一个注解和一个自定义的validator。

// startwithvalidator.java
public class startwithvalidator implements constraintvalidator<startwithvalidation, string> {
    private string start;
    @override
    public void initialize(startwithvalidation constraintannotation) {
        start = constraintannotation.start();
    }
    @override
    public boolean isvalid(string value, constraintvalidatorcontext context) {
        if (!stringutils.isempty(value)) {
            return value.startswith(start);
        }
        return true;
    }
}
// startwithvalidation.java
@documented
@constraint(validatedby = startwithvalidator.class)
@target({method, field})
@retention(runtime)
public @interface startwithvalidation {
    string message() default "不是正确的性别取值范围";
    string start() default "_";
    class[] groups() default {};
    class[] payload() default {};
    @target({method, field, annotation_type, constructor, parameter})
    @retention(runtime)
    @documented
    @interface list {
        gendervalidation[] value();
    }
}

然后在user.java中增加一个address属性，并给它加上上面这个自定义的注解，这里我们定义了一个可以传入start参数的注解，表示应该以什么开头。

@startwithvalidation(message = "param 'address' must be start with 'beijing'.", start = "beijing")
private string address;

除了定义可以作用于属性的注解外，其实还可以定义作用于class的注解（@target({type})），用于校验class的实例。

3.2 自定义validator

第一步，实现一个validator。(这种方法不需要我们的bean里面有任何注解之类的东西)

package com.example.validation.demo;
import org.springframework.stereotype.component;
import org.springframework.validation.errors;
import org.springframework.validation.validationutils;
import org.springframework.validation.validator;
@component
public class uservalidator implements validator {
    @override
    public boolean supports(class clazz) {
        return user2.class.equals(clazz);
    }
    @override
    public void validate(object target, errors errors) {
        validationutils.rejectifempty(errors, "name", "name.empty");
        user2 p = (user2) target;
        if (p.getid() == 0) {
            errors.rejectvalue("id", "can not be zero");
        }
    }
}

第二步，修改controller代码，注入上面的uservalidator实例，并给controller的方法参数加上@validated注解，即可完成和前面自定义注解一样的校验功能。

@restcontroller
public class usercontroller {
    @autowired
    uservalidator validator;
    @initbinder
    public void initbinder(webdatabinder binder) {
        binder.setvalidator(validator);
    }
    @requestmapping(value = "/user/post", method = requestmethod.post)
    public serviceresponse handvalidatepost(@validated @requestbody user user) {
        serviceresponse serviceresponse = new serviceresponse();
        serviceresponse.setcode(0);
        serviceresponse.setmessage("test");
        return serviceresponse;
    }
}

这个方法和自定义注解的区别在于不需要在bean里面添加注解，并且可以更加灵活的把一个bean里面所有的field的校验代码都搬到一起，而不是每一个属性都去加注解，如果校验的属性非常多，且默认注解的能力又不够的话，这种方式也是不错的，可以避免大量的自定义注解。

3.3 以编程的方式校验（手动）

这种方式可以算是原始的hibernate-validation的方式。直接看代码，这里有一个比较不同的是，可以使用hibernate-validation的fail fast mode。因为前面的方式，都将所有的参数都验证完了，再把错误返回。有时我们希望遇到一个参数错误，就立即返回。

设置fast-fail为true可以达到这个目的。不过貌似不能再用@validated注解方法参数了，而是要用validatorfactory创建validator。

在实际开发中，不必每次都编写代码创建validator，可以采用@configuration的方式创建，然后再@autowired注入到每个需要使用validator的controller当中。

@restcontroller
public class usercontroller {
    ...
    @requestmapping(value = "/validation/poststudent", method = requestmethod.post)
    public serviceresponse validatepoststudent(@requestbody user user) {
        // user参数前面没有@validated注解了，user类里面那些注解还是保留着即可。
        hibernatevalidatorconfiguration configuration = validation.byprovider(hibernatevalidator.class).configure();
        validatorfactory factory = configuration.failfast(true).buildvalidatorfactory(); // fastfail
        validator validator = factory.getvalidator();
        set<constraintviolation> set = validator.validate(user);
        // 根据set的size，大于0时，抛异常。由于设置了failfast，这里set最多就一个元素
        serviceresponse serviceresponse = new serviceresponse();
        serviceresponse.setcode(0);
        serviceresponse.setmessage("test");
        return serviceresponse;
    }
}

3.4 定义分组校验

有的时候，我们会有两个不同的接口，但是会使用到同一个bean来作为vo（意思是两个接口的uri不同，但参数中都用到了同一个bean）。

而在不同的接口上，对bean的校验需求可能不一样，比如接口2需要校验studentid，而接口1不需要。那么此时就可以用到校验注解的分组groups。

// user.java
public class user {
    ... 省略其他属性
    // 指明在groups={student.class}时才需要校验studentid
    @notnull(groups = {student.class}, message = "param 'studentid' must not be null.")
    private long studentid;
    // 增加student interface
    public interface student {
    }
}
// usercontroller.java，增加了一个/getstudent接口
@restcontroller
public class usercontroller {
    @requestmapping(value = "/validation/get", method = requestmethod.get)
    public serviceresponse validateget(@validated user user) {
        serviceresponse serviceresponse = new serviceresponse();
        serviceresponse.setcode(200);
        serviceresponse.setmessage("test");
        return serviceresponse;
    }
    @requestmapping(value = "/validation/getstudent", method = requestmethod.get)
    public serviceresponse validategetstudent(@validated({user.student.class}) user user) {
        serviceresponse serviceresponse = new serviceresponse();
        serviceresponse.setcode(0);
        serviceresponse.setmessage("test");
        return serviceresponse;
    }
}

到这里，也可以带一嘴valid和validated注解的区别，其代码注释写着后者是对前者的一个扩展，支持了group分组的功能。

3.5 定制返回码和消息

第二节中定义了一个serviceresponse，其实作为一个开放的api，不论用户传入任何参数，返回的结果都应该是预先定义好的格式，并且可以写明在接口文档中，即使发生了校验失败，应该返回一个包含错误码code（发生错误时一般大于0）和message字段。

{
    "code": 51000,
    "message": "param 'name' must be less than 10 characters."
}

的结果，而http status code一直都是200。

为了实现这个目的，我们加一个全局异常处理方法。

// serviceexceptionhandler.java
package com.example.validation.demo;
import org.slf4j.logger;
import org.slf4j.loggerfactory;
import org.springframework.util.collectionutils;
import org.springframework.validation.bindexception;
import org.springframework.validation.fielderror;
import org.springframework.web.bind.methodargumentnotvalidexception;
import org.springframework.web.bind.annotation.exceptionhandler;
import org.springframework.web.bind.annotation.restcontrolleradvice;
import java.util.list;
@restcontrolleradvice
public class serviceexceptionhandler {
    static final logger log = loggerfactory.getlogger(serviceexceptionhandler.class);
    @exceptionhandler(value = {exception.class})
    public serviceresponse handlebindexception(exception ex) {
        log.error("{}", ex);
        stringbuilder message = new stringbuilder();
        if (ex instanceof bindexception) {
            list fielderrorlist = ((bindexception) ex).getfielderrors();
            if (!collectionutils.isempty(fielderrorlist)) {
                for (fielderror fielderror : fielderrorlist) {
                    if (fielderror != null && fielderror.getdefaultmessage() != null) {
                        message.append(fielderror.getdefaultmessage()).append(" ");
                    }
                }
            }
        } else if (ex instanceof methodargumentnotvalidexception) {
            list fielderrorlist = ((methodargumentnotvalidexception) ex).getbindingresult().getfielderrors();
            if (!collectionutils.isempty(fielderrorlist)) {
                for (fielderror fielderror : fielderrorlist) {
                    if (fielderror != null && fielderror.getdefaultmessage() != null) {
                        message.append(fielderror.getdefaultmessage()).append(" ");
                    }
                }
            }
        }
        // 生成返回结果
        serviceresponse errorresult = new serviceresponse();
        errorresult.setcode(51000); // errorcode.param_error = 51000
        errorresult.setmessage(message.tostring());
        return errorresult;
    }
}
// user.java，注解传入指定message
public class user {
    @notblank(message = "param 'name' can't be blank.")
    @size(max=10, message = "param 'name' must be less than 10 characters.")
    private string name;
    ...
}

在上面的方法中，我们处理了bindexception（非请求body参数，例如@requestparam接收的）和methodargumentnotvalidexception（请求body里面的参数，例如@requestbody接收的），这两类exception里面都有一个bindingresult对象，它里面有一个包装成fielderror的list，保存着bean对象出现错误的field等信息。

取出它里面defaultmessage，放到统一的serviceresponse返回即可实现返回码和消息的定制。由于消息内容是有注解默认的defaultmessage决定的，为了按照自定义的描述返回，在bean对象的注解上需要手动赋值为希望返回的消息内容。

@notblank(message = "param 'name' can't be blank.")
@size(max=10,message = "param 'name' must be less than 10 characters.")
private string name;

这样当name参数长度超过10时，就会返回

{
    "code": 51000,
    "message": "param 'name' must be less than 10 characters."
}

这里的fielderror fielderror = ex.getfielderror();只会随机返回一个出错的属性，如果bean对象的多个属性都出错了，可以调用ex.getfielderrors()来获得，这里也可以看到spring validation在参数校验时不会在第一次碰到参数错误时就返回，而是会校验完成所有的参数。

如果不想手动编程去校验，那么这里可以只读取一个随机的fielderror，返回它的错误消息即可。

3.6 更加细致的返回码和消息

其实还有一种比较典型的自定义返回，就是错误码（code）和消息（message）是一一对应的，比如：

• 51001：字符串长度过长
• 51002：参数取值过大
• …

这种情况比较特殊，一般当参数错误的时候，会返回一个整体的参数错误的错误码，然后携带参数的错误信息。但有时，业务

上就要不同的参数错误，既要错误码不同，错误信息也要不同。我想了下，有两种思路。

• 第一种：通过message同时包含错误码和错误信息，在全局异常捕获方法中，再把它们拆开。
• 第二种：手动校验，抛出自定义的exception（里面带有code、message）。手动校验这里，如果每一个controller都去写一遍，确实比较费劲，可以结合aop来实现，或者抽出一个基类basecontroller的方式。

四、小结

其实在实际的工作中，肯定还有更复杂的校验逻辑，但是不一定非要都用框架去实现，框架里面的实现（比如注解）应该是一个比较简单通用的校验，能够达到复用，减少重复的劳动。

而更加复杂的逻辑校验，一定是存在具体业务当中的，最好是在业务代码里面实现。

还有一点需要注意，spring validation的isvalid方法，如果返回false，那么controller不再会被调用，而是直接返回。如果你在controller上面加了aop进行接口调用统计的话，可能会漏掉。

这个时候，我们不应该让controller不调用，建议这种情况在aop里面对controller的参数切面进行校验后，抛出统一的业务异常。

以上为个人经验，希望能给大家一个参考，也希望大家多多支持。