09-详解JSR303规范及其对应的校验框架的使用

JSR303规范

校验注解

前端请求后端接口时传输的参数在Controller和Service中都要校验但分工不同,因为你无法保证Service接口一定是由Controller层调用

• Controller中的校验代码是通用的: 主要是校验请求参数的合法性，包括必填项校验、数据格式校验(如日期格式)

• Service中的校验代码需要根据业务规则编写: 校验的是业务规则相关的内容,比如课程是否已经审核通过,如果未通过则提交失败等

早在JavaEE6规范中就定义了参数校验的JSR-303规范,通过Bean Validation即对Bean的属性进行校验

• SpringBoot提供了JSR-303规范的支持依赖spring-boot-stater-validation,底层使用的Hibernate Validation也是对Bean Validation的参考实现

在javax.validation.constraints包下有很多这样的校验注解,直接使用注解定义校验规则即可

限制	说明
@Null	限制只能为null
@NotNull	限制制必须不为null
@AssertFalse	限制必须为false
@AssertTrue	限制必须为true
@DecimalMax(value)	限制必须为一个不大于指定值的数字
@DecimalMin(value)	限制必须为一个不小于指定值的数字
@Digits(integer,fraction)	限制必须为一个小数,且整数部分的位数不能超过integer,小数部分的位数不能超过fraction
@Max(value)	限制必须为一个不大于指定值的数字
@Min(value)	限制必须为一个不小于指定值的数字
@Future	限制必须是一个将来的日期
@Past	限制必须是一个过去的日期
@Pattern(value)	限制必须符合指定的正则表达式
@Size(max, min)	限制字符长度必须在min到max之间
@NotEmpty	验证注解的元素值不为null且不为空(字符串长度不为0、集合大小不为0)
@NotBlank	验证注解的元素值不为null且不为空(去除首位空格后长度不为0) 不同于@NotEmpty,@NotBlank只应用于字符串且在比较时会去除字符串的空格
@Email	验证注解的元素值是Email,也可以通过正则表达式和flag指定自定义的email格式

使用校验框架

第一步: 在Base工程中引入spring-boot-starter-validation依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

第二步: 在添加课程接口的请求参数对应的模型对象AddCourseDto的属性上添加validation提供的校验规则

@Data
@ApiModel(value = "AddCourseDto", description = "新增课程基本信息")
public class AddCourseDto {
+   @NotEmpty(message = "课程名称不能为空")
    @ApiModelProperty(value = "课程名称", required = true)
    private String name;

+   @NotEmpty(message = "适用人群不能为空")
+   @Size(min = 10, message = "适用人群内容过少，至少10个字符")
    @ApiModelProperty(value = "适用人群", required = true)
    private String users;

    @ApiModelProperty(value = "课程标签")
    private String tags;

+   @NotEmpty(message = "课程分类不能为空")
    @ApiModelProperty(value = "大分类", required = true)
    private String mt;

+   @NotEmpty(message = "课程分类不能为空")
    @ApiModelProperty(value = "小分类", required = true)
    private String st;

+   @NotEmpty(message = "课程等级不能为空")
    @ApiModelProperty(value = "课程等级", required = true)
    private String grade;

    @ApiModelProperty(value = "教学模式（普通，录播，直播等）", required = true)
    private String teachmode;

    @ApiModelProperty(value = "课程介绍")
    private String description;

    @ApiModelProperty(value = "课程图片", required = true)
    private String pic;

+   @NotEmpty(message = "收费规则不能为空")
    @ApiModelProperty(value = "收费规则，对应数据字典", required = true)
    private String charge;

    @ApiModelProperty(value = "价格")
    private Float price;

    @ApiModelProperty(value = "原价")
    private Float originalPrice;

    @ApiModelProperty(value = "qq")
    private String qq;

    @ApiModelProperty(value = "微信")
    private String wechat;

    @ApiModelProperty(value = "电话")
    private String phone;

    @ApiModelProperty(value = "有效期")
    private Integer validDays;
}

第三步: 在Controller方法中添加@Validated注解表示开启校验,这里对内容管理模块添加课程接口进行校验

@ApiOperation("新增课程基础信息接口")
@PostMapping("/course")
public CourseBaseInfoDto createCourseBase(@RequestBody @Validated AddCourseDto addCourseDto) {
    // 机构id暂时写死
    Long companyId = 22L;
    return courseBaseInfoService.createCourseBase(companyId, addCourseDto);
}

第四步: 如果校验出错Spring会抛出MethodArgumentNotValidException异常,所以我们需要在全局异常处理器中捕获异常并解析出所有异常信息返回给前端

@ExceptionHandler(MethodArgumentNotValidException.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public RestErrorResponse doMethodArgumentNotValidException(MethodArgumentNotValidException exception) {
    // 由于用户输入的内容可能存在多处错误，所以我们要将所有错误信息都提示给用户
    BindingResult bindingResult = exception.getBindingResult();
    // 获取错误信息的集合
    List<FieldError> fieldErrors = bindingResult.getFieldErrors();
    // 拼接字符串
    StringBuffer stringBuffer = new StringBuffer();
    fieldErrors.forEach(fieldError -> stringBuffer.append(fieldError.getDefaultMessage()).append(","));
    // 记录日志
    log.error(stringBuffer.toString());
    // 将错误信息响应给用户
    return new RestErrorResponse(stringBuffer.toString());
}


// 采用Stream流的方式
@ExceptionHandler(MethodArgumentNotValidException.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public RestErrorResponse methodArgumentNotValidException(MethodArgumentNotValidException e) {
    BindingResult bindingResult = e.getBindingResult();
    List<String> msgList = new ArrayList<>();
    // 获取包含所有错误信息的集合,并将集合中的错误信息放在msgList集合中
    bindingResult.getFieldErrors().stream().forEach(item->msgList.add(item.getDefaultMessage()));
    // 将集合中的错误信息以逗号分隔
    String msg = StringUtils.join(msgList, ",");
    log.error("【系统异常】{}",msg);
    return new RestErrorResponse(msg);
}

第五步: 启动内容管理服务并使用HTTP Client进行测试,将必填项设置为空并且适用人群设置小于10个字,查看接口响应结果

POST http://localhost:53040/content/course

HTTP/1.1 500 
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 03 Feb 2023 04:52:30 GMT
Connection: close

{
  "errMessage": "课程名称不能为空,适用人群内容过少，至少10个字符,"
}

分组校验

有时候在同一个属性上设置一个校验规则不能满足要求,比如添加订单时订单编号是由系统生成的所以要求为空,但是在更新订单时要求订单编号不能为空

分组校验就是在同一个属性中定义多个校验规则其分别属于不同的分组

@Null(message = "订单id需为空", groups = Insert.class)// 对于id属性在insert分组中要求订单id为空
@NotEmpty(message = "订单id不能为空", groups = Update.class)// 对于id属性在Update分组中要求订单id不能为空
private String id;

第一步: 定义校验分组,由于校验分组是公用的,所以在base工程中使用class类型(如空接口)来表示不同的分组

package com.xuecheng.base.exception;
/**
 * @description 校验分组
 */
public class ValidationGroups {
    public interface Insert{}
    public interface Update{}
    public interface Delete{}
}

第二步: 在定义校验规则时指定分组

@NotEmpty(message = "添加课程名称不能为空", groups = ValidationGroups.Insert.class)
@NotEmpty(message = "修改课程名称不能为空", groups = ValidationGroups.Update.class)
@ApiModelProperty(value = "课程名称", required = true)
private String name;

第三步: 在接口方法中启动校验规则并在@Validated注解的value属性中指定要使用的分组名,这里添加课程的接口对应的分组即为ValidationGroups.Insert

@ApiOperation("新增课程基础信息接口")
@PostMapping("/course")
public CourseBaseInfoDto createCourseBase(@RequestBody @Validated(ValidationGroups.Insert.class) AddCourseDto addCourseDto) {
    Long companyId = 22L;
    return courseBaseInfoService.createCourseBase(companyId, addCourseDto);
}

第四步: 使用HTTP Client测试,查看响应结果

POST http://localhost:53040/content/course

HTTP/1.1 500 
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 03 Feb 2023 05:28:23 GMT
Connection: close
// 由于接口方法中指定的是Insert分组,所以抛出异常信息添加课程名称不能为空,同理对于Update分组则异常信息为修改课程名称不能为空
{
  "errMessage": "添加课程名称不能为空,"
}

自定义校验规则

如果javax.validation.constraints包下的校验规则满足不了需求我们可以手写校验代码或者自定义校验规则注解