JSR-303 是 JAVA EE 6 中的一项子规范，叫做 Bean Validation，官方参考实现是Hibernate Validator。

注意：JSR-303实现与 Hibernate ORM 没有任何关系。 JSR 303 用于对 Java Bean 中的字段的值进行验证。

Spring MVC 3.x 之中也大力支持 JSR-303，可以在控制器中对表单提交的数据方便地验证。

@Valid注解使用

使用步骤

在Controller中使用 @Valid+BindingResult做参数校验非常好用。一般步骤如下：

（1）引入pom依赖

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
<!-- @JsonFormat注解需要引入-->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
        </dependency>

(2）在入参bean类中需要校验的参数上使用校验注解

在bean类中的字段加上校验注解，比如：@NotBlank(message = “ID 不能为空”)
每个字段可以加上多个校验注解。
如果 bean需要交给Spring容器管理，可以加上 @Conmponent注解。

（3）编写Controller层代码

在入参的请求体前加@Valid注解
请求体后加 BindingResult bindingResult 此类为bean校验捕获到的异常储存。
对于 BindingResult信息，我们业务做统一校验信息处理。

注意：

（1）@Valid与 BindingResult要配套使用。

（2）@Valid使用

可以用在方法、构造函数、方法参数和成员属性（field）上；
可以进行嵌套校验，但是，需要在嵌套的字段上面加上@Valid注解；
不能进行分组校验；

示例1使用

（1）请求体

@Data
public class AaSaveRequest extends BaseRequest {
    private static final long serialVersionUID = -7895168538160321157L;

    @NotEmpty(message = "用户名不能为空")
    private String username;

    @NotNull(message = "createTime不能为空")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private Date createTime;

    private Boolean delFlag;
    
}

（2）controller请求方法

@PostMapping("/save")
public WebResult save(@RequestBody @Valid AaSaveRequest saveRequest, BindingResult bindingResult) {
    if (bindingResult.hasErrors()) {
        //如果有校验错误，返回第一个校验信息
        String defaultMessage = bindingResult.getFieldErrors().get(0).getDefaultMessage();

        //将错误信息返回或者抛异常全局处理。
        WebResult webResult = new WebResult();
        webResult.setSuccess(false);
        webResult.setMessage(defaultMessage);
        return webResult;
    }
    BaseOperateResult operateResult = aaService.save(saveRequest);
    if (!operateResult.isSuccess()) {
        WebResult.error().message(operateResult.getErrorCode().getMessage());
    }
    return WebResult.ok();
}

bindingResult.hasErrors() 判断是否校验通过，未通过bindingResult.getFieldError().getDefaultMessage()获取在TestEntity的属性设置的自定义message，如果没有设置，则返回默认值"javax.validation.constraints.XXX.message"。

示例2使用

我们将实示例1中 controller请求方法对于校验错误采用全局异常捕获的方式处理。

（1）自定义异常类

自定义异常，或者捕获 MethodArgumentNotValidException异常。

/**
 * 参数校验异常类
 */
public class ParameterCheckException extends RuntimeException {
    private static final long serialVersionUID = -4163815498400849756L;

    public ParameterCheckException(String message) {
        super(message);
    }

}

（2）全局异常处理

/**
 * 全局异常处理类
 */
@Slf4j
@ResponseBody
@ControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(value = ParameterCheckException.class)
    private WebResult handlerParameterCheckException(ParameterCheckException e) {
        //log.error("ParameterCheckException 异常 -> error = {}", e);
        WebResult webResult = new WebResult();
        webResult.setSuccess(false);
        webResult.setCode(WebHttpCode.SERVICE_ERROR);
        webResult.setMessage(e.getMessage());
        return webResult;
    }

}

(3）controller请求方法改造

@PostMapping("/save")
public WebResult save(@RequestBody @Valid AaSaveRequest saveRequest, BindingResult bindingResult) {
    if (bindingResult.hasErrors()) {
        //如果有校验错误，返回第一个校验信息
        String defaultMessage = bindingResult.getFieldErrors().get(0).getDefaultMessage();
        //将错误信息返回或者抛异常全局处理。
        throw new ParameterCheckException(defaultMessage);
    }
    BaseOperateResult operateResult = aaService.save(saveRequest);
    if (!operateResult.isSuccess()) {
        WebResult.error().message(operateResult.getErrorCode().getMessage());
    }
    return WebResult.ok();
}

测试访问校验ok

嵌套使用

嵌套使用，比如：A类中引用B类，且A、B二类都有内部校验，为了使B类也生效，在A类中引用B类时，在B类变量上加@Valid注解，如果B类不能为空时还需要再加@NotNull。

1	注意：嵌套验证时必须使用 @Valid注解。

（1）请求体

@Data
public class AaSave2Request extends BaseRequest {
    private static final long serialVersionUID = -7895168538160321157L;

    @NotEmpty(message = "用户名不能为空")
    private String username;

    @NotNull(message = "createTime不能为空")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private Date createTime;

    private Boolean delFlag;

    /**
     * 嵌套验证时必须使用 @Valid注解
     */
    @Valid
    @NotNull(message = "文件不能为空")
    private AaSaveFileRequest aaSaveFileRequest;
    
}

（2）controller请求方法

@PostMapping("/save2")
public WebResult save2(@RequestBody @Valid AaSave2Request save2Request, BindingResult bindingResult) {
    if (bindingResult.hasErrors()) {
        //如果有校验错误，返回第一个校验信息
        String defaultMessage = bindingResult.getFieldErrors().get(0).getDefaultMessage();
        //将错误信息返回或者抛异常全局处理。
        throw new ParameterCheckException(defaultMessage);
    }
    BaseOperateResult operateResult = aaService.save2(save2Request);
    if (!operateResult.isSuccess()) {
        WebResult.error().message(operateResult.getErrorCode().getMessage());
    }
    return WebResult.ok();
}

@Validated注解使用

示例1使用

（1）请求体

@Data
public class AaUpdateRequest extends BaseRequest {
    private static final long serialVersionUID = -8386003857309634939L;

    @NotNull(message = "id不能为空")
    private Long id;

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

    @NotNull(message = "createTime不能为空")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private Date createTime;

    private Boolean delFlag;

}

（2）controller请求方法

@PostMapping("/update")
public WebResult update(@RequestBody @Validated AaUpdateRequest updateRequest, BindingResult bindingResult) {
    if (bindingResult.hasErrors()) {
        //如果有校验错误，返回第一个校验信息
        String defaultMessage = bindingResult.getFieldErrors().get(0).getDefaultMessage();
        throw new ParameterCheckException(defaultMessage);
    }
    BaseOperateResult operateResult = aaService.update(updateRequest);
    if (!operateResult.isSuccess()) {
        WebResult.error().message(operateResult.getErrorCode().getMessage());
    }
    return WebResult.ok();
}

示例2使用

我们将实示例1中 controller请求方法对于校验错误采用全局异常捕获的方式处理。

（1）全局异常处理，捕获 MethodArgumentNotValidException异常

/**
 * 全局异常处理类
 */
@Slf4j
@ResponseBody
@ControllerAdvice
public class GlobalExceptionHandler {
    
    /**
     * 处理 @Valid和 @Validated注解参数校验失败异常
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public WebResult exceptionHandler(MethodArgumentNotValidException exception) {
        WebResult webResult = new WebResult();
        webResult.setSuccess(false);
        webResult.setCode(WebHttpCode.SERVICE_ERROR);

        BindingResult bindingResult = exception.getBindingResult();
        if (bindingResult.hasErrors()) {
            //如果有校验错误，返回第一个校验信息
            String defaultMessage = bindingResult.getFieldErrors().get(0).getDefaultMessage();
            webResult.setMessage(defaultMessage);
        }
        return webResult;
    }

}

（2）controller请求方法改造

这里单独使用 @Validated注解。

@PostMapping("/update2")
public WebResult update2(@RequestBody @Validated AaUpdateRequest updateRequest) {
    BaseOperateResult operateResult = aaService.update(updateRequest);
    if (!operateResult.isSuccess()) {
        WebResult.error().message(operateResult.getErrorCode().getMessage());
    }
    return WebResult.ok();
}

嵌套使用

@Validated无法单独提供嵌套验证功能。不能用在成员属性上，能配合嵌套验证注解@Valid进行嵌套验证。

（1）请求体

@Data
public class AaUpdate3Request extends BaseRequest {
    private static final long serialVersionUID = 2976273808489796719L;

    @NotNull(message = "id不能为空")
    private Long id;

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

    @NotNull(message = "createTime不能为空")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private Date createTime;

    private Boolean delFlag;
    
    /**
     * 嵌套验证时必须使用 @Valid注解
     */
    @Valid
    @NotNull(message = "文件不能为空")
    private List<AaSaveFileRequest> fileRequestList;

}

（2）controller请求方法

@PostMapping("/update3")
public WebResult update3(@RequestBody @Validated AaUpdate3Request update3Request) {
    BaseOperateResult operateResult = aaService.update3(update3Request);
    if (!operateResult.isSuccess()) {
        WebResult.error().message(operateResult.getErrorCode().getMessage());
    }
    return WebResult.ok();
}

如果想了解 @Validated注解分组校验请查看参考文章。

@Valid 和 @Validated 区别

先看下两者的源码：

@Valid 包位置：javax.validation

@Target({ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Valid {
}

@Validated 包位置 org.springframework.validation.annotation，是 Spring 做得一个自定义注解，增强了分组功能（对 @Valid的封装）；只在 Spring Validator 校验机制使用。

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Validated {
    Class<?>[] value() default {};
}

相同点：

@Valid 和 @Validated 两者都可以对数据进行校验，在校验字段上加上规则注解（@NotNull, @NotEmpty等）都可以对 @Valid 和 @Validated 生效。
@Valid 和 @Validated 两者都可以与 BindingResult bindingResult配对出现，并且形参顺序是固定的（一前一后），controller对 BindingResult处理返回校验提示。
@Valid 和 @Validated 两者也可以单独使用，单独使用当校验不通过时会抛出 BindException异常。这时需要再写一个全局校验异常捕获处理类，然后返回校验提示。

不同点：

@Valid可以用在方法、构造函数、方法参数和成员属性（field）上；
@Valid可以进行嵌套校验，但是，需要在嵌套的字段上面加上@Valid注解；
@Valid不支持分组。
@Validated可以用在方法、构造函数、方法参数；但是不能用在成员属性（字段）上；
@Validated不支持嵌套校验，因为不能用在成员属性（字段）上；
@Validated支持分组验证，以在入参验证时，根据不同的分组采用不同的验证机制；

项目中使用 @Valid和@Validated都可以。如果涉及分组校验时，使用 @Validated注解。

@Valid无法单独提供嵌套验证功能。能够用在成员属性上，能配合嵌套验证注解@Valid进行嵌套验证。
@Validated无法单独提供嵌套验证功能。不能用在成员属性上，能配合嵌套验证注解@Valid进行嵌套验证。

全局异常捕获处理

一般entity的参数校验，异常就这如下三种：

BindException

（@Validated @Valid仅对于表单提交有效，对于以json格式提交将会失效**）**

@ResponseStatus(HttpStatus.BAD_REQUEST)
@ExceptionHandler(BindException.class)
public ResultVO bindExceptionHandler(BindException e) {
    List<FieldError> fieldErrors = e.getBindingResult().getFieldErrors();
    List<String> msgList = fieldErrors.stream()
            .map(o -> o.getDefaultMessage())
            .collect(Collectors.toList());
    String messages = StringUtils.join(msgList.toArray(), ";");
    log.error("Validation格式校验异常:-------------->{}",messages);
    return ResultVO.builder().errorcode(HttpStatus.BAD_REQUEST.value()).errormessage(messages).build();
}

MethodArgumentNotValidException

（@Validated @Valid 前端提交的方式为json格式有效，出现异常时会被该异常类处理**）**

@ResponseStatus(HttpStatus.BAD_REQUEST)
@ExceptionHandler(BindException.class)
public ResultVO bindExceptionHandler(BindException e) {
    List<FieldError> fieldErrors = e.getBindingResult().getFieldErrors();
    List<String> msgList = fieldErrors.stream()
            .map(o -> o.getDefaultMessage())
            .collect(Collectors.toList());
    String messages = StringUtils.join(msgList.toArray(), ";");
    log.error("Validation格式校验异常:-------------->{}",messages);
    return ResultVO.builder().errorcode(HttpStatus.BAD_REQUEST.value()).errormessage(messages).build();
}

ConstraintViolationException

（@NotBlank @NotNull @NotEmpty）

@ResponseStatus(HttpStatus.BAD_REQUEST)
@ExceptionHandler(value = ConstraintViolationException.class)
public ResultVO handler(ConstraintViolationException e) throws IOException {
    List<String> msgList = new ArrayList<>();
    for (ConstraintViolation<?> constraintViolation : e.getConstraintViolations()) {
        msgList.add(constraintViolation.getMessage());
    }
    String messages = StringUtils.join(msgList.toArray(), ";");
    log.error("entity格式校验异常:-------------->{}",messages);
    return ResultVO.builder().errorcode(400).errormessage(messages).build();
}

自定义校验注解

虽然JSR303和springboot-validator 已经提供了很多校验注解，但是当面对复杂参数校验时，还是不能满足我们的要求，这时候我们就需要自定义校验注解。

以下例子为：自定义一个校验注解@ListValue，指定参数取值只能0和1。

自定义校验步骤：

编写一个自定义的校验注解
编写一个自定义的校验器
关联自定义的校验器和自定义的校验注解

导入注解校验依赖

导入注解依赖的校验包

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

创建注解

创建 ListValue/AddGroup/UpdateGroup，后两者对应规则对应group

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

import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
import static java.lang.annotation.ElementType.CONSTRUCTOR;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.PARAMETER;
import static java.lang.annotation.ElementType.TYPE_USE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

/**
 * 校验注解
 *
 * @description
 * 可以参考 NotBlank 注解
 */

@Documented
// 会在下边定义一个校验器类 validatedBy = ListValueConstraintValidator.class
@Constraint(validatedBy = { })
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
@Retention(RUNTIME)
public @interface ListValue {

  // String message() default "{javax.validation.constraints.NotBlank.message}";
  // 这里使用自定义的message,在resource下创建新的配置文件
  String message() default "{com.atguigu.common.valid.ListValue.message}";

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

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

  int[] vals() default {};

}

/**
 * @Description: 用于Add操作验证
 **/
public interface AddGroup {
}

/**
 * @Description: 用于Update操作验证
 **/
public interface UpdateGroup {
}

创建自定义注解消息配置文件:
/src/main/resources/ValidationMessages.properties

1	com.atguigu.common.valid.ListValue.message=必须提交指定的值

自定义注解说明：

一个标注(annotation) 是通过@interface关键字来定义的. 这个标注中的属性是声明成类似方法
的样式的. 根据Bean Validation API 规范的要求：

message属性, 这个属性被用来定义默认得消息模版, 当这个约束条件被验证失败的时候,通过
此属性来输出错误信息。
groups 属性, 用于指定这个约束条件属于哪(些)个校验组. 这个的默认值必须是Class<?>类型数组。
payload 属性, Bean Validation API 的使用者可以通过此属性来给约束条件指定严重级别. 这个属性并不被API自身所使用。

除了这三个强制性要求的属性(message, groups 和 payload) 之外, 我们还添加了一个属性用来指定所要求的值. 此属性的名称vals在annotation的定义中比较特殊, 如果只有这个属性被赋值了的话, 那么, 在使用此annotation到时候可以忽略此属性名称。

另外, 我们还给这个annotation标注了一些元标注( metaannotatioins)：

@Target({ METHOD, FIELD, ANNOTATION_TYPE }): 表示此注解可以被用在方法, 字段或者
annotation声明上。
@Retention(RUNTIME): 表示这个标注信息是在运行期通过反射被读取的.
@Constraint(validatedBy = ListValueConstraintValidator.class): 指明使用哪个校验器(类) 去校验使用了此标注的元素.
@Documented: 表示在对使用了该注解的类进行javadoc操作到时候, 这个标注会被添加到javadoc当中.

创建校验器

ListValueConstraintValidator

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

/**
 * 约束校验器
 *
 * @author: kaiyi
 * @create: 2020-08-21 11:30
 */
public class ListValueConstraintValidator implements ConstraintValidator<ListValue,Integer> {

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

  /**
   * 初始化方法
   *
   * @param constraintAnnotation
   */
  @Override
  public void initialize(ListValue constraintAnnotation) {
    int[] vals = constraintAnnotation.vals();
    for (int val : vals) {
      set.add(val);
    }

  }

  /**
   * 判断是否校验成功
   *
   * @param value 需要校验的值
   * @param context
   * @return
   */
  @Override
  public boolean isValid(Integer value, ConstraintValidatorContext context) {
    return set.contains(value);
  }
}

ListValueConstraintValidator定义了两个泛型参数, 第一个是这个校验器所服务到标注类型(在我们的例子中即ListValue), 第二个这个校验器所支持到被校验元素的类型 (即Integer)。

如果一个约束标注支持多种类型的被校验元素的话, 那么需要为每个所支持的类型定义一个ConstraintValidator,并且注册到约束标注中。

这个验证器的实现就很平常了, initialize()方法传进来一个所要验证的标注类型的实例, 在本例中, 我们通过此实例来获取其vals属性的值,并将其保存为Set集合中供下一步使用。

isValid()是实现真正的校验逻辑的地方, 判断一个给定的int对于@ListValue这个约束条件来说是否是合法的。

在参数对象中为 showStatus 属性使用 @ListValue 注解。
com/atguigu/gulimall/product/entity/BrandEntity.java

import com.atguigu.common.valid.ListValue;
import com.atguigu.common.valid.group.AddGroup;
import com.atguigu.common.valid.group.UpdateGroup;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;

import java.io.Serializable;
import lombok.Data;
import org.hibernate.validator.constraints.URL;

import javax.validation.constraints.Min;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotEmpty;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Null;
import javax.validation.constraints.Pattern;

/**
 * 品牌
 * 
 * @author kaiyi
 * @email corwienwong@gmail.com
 * @date 2020-08-10 15:45:20
 */
@Data
@TableName("pms_brand")
public class BrandEntity implements Serializable {
    private static final long serialVersionUID = 1L;

    /**
     * 品牌id
     */
    @TableId
    @NotNull(message = "修改必须指定品牌id", groups = {UpdateGroup.class})
    @Null(message = "新增不能指定id", groups = {AddGroup.class})
    private Long brandId;
    /**
     * 品牌名
     */
    @NotBlank(message = "品牌名不能为空", groups = {AddGroup.class, UpdateGroup.class})
    private String name;
    /**
     * 品牌logo地址
     */
    @NotEmpty(message = "URL地址不能为空", groups = {AddGroup.class})
    @URL(message = "logo必须是一个合法的url地址", groups = {AddGroup.class, UpdateGroup.class})
    private String logo;
    /**
     * 介绍
     */
    private String descript;
    /**
     * 显示状态[0-不显示；1-显示]
     */
    //@Pattern()
    // 使用自定义校验注解
    @ListValue(vals = {0,1}, groups = {AddGroup.class, UpdateGroup.class})
    private Integer showStatus;
    /**
     * 检索首字母
     */
    @NotEmpty
    @Pattern(regexp = "/^[a-zA-Z]$/", message = "检索首字母必须是一个字母", groups = {AddGroup.class, UpdateGroup.class})
    private String firstLetter;
    /**
     * 排序
     */
    @NotNull
    @Min(value = 0, message = "排序必须大于等于0", groups = {AddGroup.class, UpdateGroup.class})
    private Integer sort;

}