编码技巧——参数校验

ゞ浴缸里的玫瑰 2023-09-29 08:45 12阅读 0赞

在日常开发写HTTP接口时，无论是对于C端接口，还是管理后台接口，接口参数校验这一部分是必须的；有一些设计业务逻辑的参数校验是可以自己去做，用状态码返回提示和message；但是一些简单参数的校验，如非空、非空字符串、集合大小等，这些如果全部用代码去做，显得十分麻烦，代码也会失去优雅性；

常见的一些校验：

日期填写，需要做NotNull的校验；  
库存填写，要做非空、数值范围为正整数、数值上限的校验；  
用户名设置，需要做非空、非空字符串、字符最大最小个数的校验；

Spring提供了这部分功能，一些基本参数的校验是可以满足的，本篇介绍一下用法；

### （1）导包 ###

javax.validation里面只有基本的@NotNull非空校验，而hibernate-validator包下的检验功能更加丰富，根据实际需要来引用，建议直接使用hibernate-validator包；本篇后面讲述的注解均来自hibernate-validator包；

<dependency>
        <groupId>javax.validation</groupId>
        <artifactId>validation-api</artifactId>
        <version>${javax.validation.api.version}</version>
    </dependency>
    <dependency>
        <groupId>org.hibernate</groupId>
        <artifactId>hibernate-validator</artifactId>
        <version>${hibernate.validation.version}</version>
    </dependency>
    
    <javax.validation.api.version>2.0.1.Final</javax.validation.api.version>
    <hibernate.validation.version>5.2.4.Final</hibernate.validation.version>

### （2）注册校验器的Bean ###

需要声明一个bean注册到spring容器，这个bean是一个容器化处理器，会把校验的逻辑通过AOP织入有@Validated注解的class；

注意：这一步在springboot其实也不用做，ValidationAutoConfiguration这个配置类自动帮我们做了，如下：

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LiD5rW35YGl5Lq6_size_20_color_FFFFFF_t_70_g_se_x_16][]

对于老的SpringMvc工程，需要我们手动的在XML中注册这个bean：

![watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LiD5rW35YGl5Lq6_size_20_color_FFFFFF_t_70_g_se_x_16 1][]

### （3）有哪些校验功能 ###

使用方式为加上对应字段需要的注解，以及注解属性（限制条件参数、异常时提示msg）即可；

Hibernate Validator 是 Bean Validation 的参考实现 。Hibernate Validator 提供了 JSR 303 规范中所有内置 constraint 的实现，除此之外还有一些附加的 constraint；

// (1) Bean Validation 中内置的 constraint
    @Valid	被注释的元素是一个对象，需要检查此对象的所有字段值
    @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(value)	被注释的元素必须符合指定的正则表达式
    
    // (2) Hibernate Validator 附加的 constraint
    @Email	被注释的元素必须是电子邮箱地址
    @Length(min=, max=)	被注释的字符串的大小必须在指定的范围内
    @NotEmpty	被注释的字符串的必须非空
    @Range(min=, max=)	被注释的元素必须在合适的范围内
    @NotBlank	被注释的字符串的必须非空
    @URL(protocol=, host=, port=, regexp=, flags=)	被注释的字符串必须是一个有效的url

区分下@NotNull/@NotEmpty/@NotBlank 3个注解的区别：

@NotNull  任何对象的value不能为null
    @NotEmpty  集合对象的元素不为0，即集合不为空，也可以用于字符串不为null
    @NotBlank  只能用于字符串不为null，并且字符串trim()以后length要大于0

### （4）如何使用参数校验 ###

**1. 方法参数，在方法声明时使用**

/**
     * @author AA
     * @description 文本协议类管理
     * @date 2020/5/11
     */
    @RestController
    @RequestMapping("/api/oms/text")
    @Validated
    public class TextManageController {
    
    	// {...}
        /**
         * 查询协议文本列表
         *
         * @param pageNum
         * @param pageSize
         * @return
         */
        @OperatorLog(operateType = OptInfo.OptType.QUERY, description = "查询文本协议列表")
        @RequestMapping(value = "/r/pageQuery", method = RequestMethod.GET)
        @ResponseBody
        public DefaultResponseDTO<DefaultPageDTO<TextDTO>> pageQuery(@Range(min = 1, message = "pageNum > 0") Integer pageNum,
                                                                     @Range(min = 10, max = 100) Integer pageSize) {
            DefaultPageDTO<TextDTO> texts = textManageService.queryTexts(pageNum, pageSize);
            return DefaultResponseDTO.success(texts);
        }
    	
    	// {...}
    }

**注意**：

（1）方法所在的类名（实现类，如controller、serviceImpl）需要加注解**@Validated**  
（2）校验失败会抛出**ConstraintViolationException**异常

**2. 实体参数，实体对象作为方法的参数**

给参数实体类增加校验注解：

/**
     * @author AA
     * @description 奖品发放接口请求体
     * @date 2020/6/3
     */
    @Data
    public class AwardSendReqDTO implements Serializable {
    
        // {...}
        /**
         * 必须,用户id
         */
        @NotNull(message = "openid不能为null")
        private String openid;
    
        /**
         * 必须,业务方的流水单号，做幂等
         */
        @NotNull(message = "requestNo不能为null")
        @Size(min = 32, max = 32, message = "requestNo长度为32")
        private String requestNo;
    
        // {...}
    }

在方法声明处（controller或service接口），对入参对象加**@Valid**注解：

@Validated
    @Slf4j
    @org.apache.dubbo.config.annotation.DubboService
    public class AwardSendFacadeImpl implements AwardSendFacade {
    	// {...}
        @Override
        @SentinelResource(value = "sendAward")
        public FacadeDefaultDTO<Boolean> sendAward(@Valid MemberAwardSendReqDTO req) {
            // {...}
        }
    	
        // {...}
    }

并且，在方法实现类（controller或serviceImpl），对类加上**@Validated**注解；

除了以上的校验，可一个自定义校验器（可参考下方的[文献\[3\]][3]），或者通过注解+切面方式实现更为复杂的参数校验如登录态校验（参考[客户端HTTP请求封装&登录态校验][HTTP]）；

参考：

[Hibernate Validator学习笔记][Hibernate Validator]

[springboot参数校验详解][springboot]

[Spring进入Controller前参数校验及自定义校验器][3]

[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LiD5rW35YGl5Lq6_size_20_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/080f7c0d824343c99f633b17b7bb27de.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5LiD5rW35YGl5Lq6,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_d3F5LXplbmhlaQ_shadow_50_text_Q1NETiBA5LiD5rW35YGl5Lq6_size_20_color_FFFFFF_t_70_g_se_x_16 1]: https://img-blog.csdnimg.cn/2a3e1b7abe4f4cdfabe0cda3a9e05099.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5LiD5rW35YGl5Lq6,size_20,color_FFFFFF,t_70,g_se,x_16
[3]: https://www.cnblogs.com/maple92/p/10780243.html
[HTTP]: https://blog.csdn.net/minghao0508/article/details/123972827
[Hibernate Validator]: https://blog.csdn.net/u011851478/article/details/51842157
[springboot]: https://www.jianshu.com/p/89a675b7c900