Spring Boot 自定义 Hibernate 验证器优雅验证枚举类型的请求参数

末蓝、 2022-12-23 12:27 245阅读 0赞

当我们后端 restful 开发的时候，作为安全开发必须在对一些参数进行校验。在我最开始写代码的时候，把请求参数的校验逻辑写在业务逻辑当中。其实还有更加优雅的方式去进行参数校验，那就是通过 hibernate-validate 通过注册的方式来进行业务校验。

## 1、一个简单的 Demo ##

我们首先通过一个 Spring boot 项目来简单的认识一下如何使用 hibernate-validator 来进行请求数据的校验。这里我们使用的是 maven 来进行项目依赖管理的。

### 1.1 pom 依赖 ###

主要是引入 `spring-boot-starter-web` web 项目相关与 `spring-boot-starter-validation` 校验相关的 starter 依赖。

<?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
        <parent>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-parent</artifactId>
            <version>2.1.4.RELEASE</version>
            <relativePath/> 
        </parent>
        <groupId>com.example</groupId>
        <artifactId>demo</artifactId>
        <version>0.0.1-SNAPSHOT</version>
        <name>demo</name>
        <description>Demo project for Spring Boot</description>
    
        <properties>
            <java.version>1.8</java.version>
        </properties>
    
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-validation</artifactId>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>
            <dependency>
                <groupId>org.apache.commons</groupId>
                <artifactId>commons-lang3</artifactId>
            </dependency>
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <optional>true</optional>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-test</artifactId>
                <scope>test</scope>
            </dependency>
        </dependencies>
    
        <build>
            <plugins>
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                </plugin>
            </plugins>
        </build>
    
    </project>

### 1.2 DemoApplication.java ###

Spring Boot 的项目启动类。

@SpringBootApplication
    public class DemoApplication { 
    
        public static void main(String[] args) { 
            SpringApplication.run(DemoApplication.class, args);
        }
    
    }

### 1.3 OrderQueryRequest.java ###

订单请求类，需要请求方必须传递商户号、订单号以及订单状态。

@Data
    public class OrderQueryRequest { 
    
        @NotBlank(message = "merchant id must not be null")
        private String merchantId;
    
        @NotBlank(message = "order id must not be null")
        private String orderId;
    
        @NotBlank(message = "order status must not be null")
        private String orderStatus;
    
    }

### 1.4 TestController.java ###

校验测试类，访问 `http://localhost:8080/test/valid` 这个接口，配合 Spring 框架提供的 @Validated 注解，来校验请求对象OrderQueryRequest。

@RestController
    @RequestMapping("test")
    public class TestController { 
    
        @RequestMapping("valid")
        public String valid(@RequestBody @Validated OrderQueryRequest request){ 
            System.out.println(request);
            return "ok";
        }
    
    }

### 1.5 校验 ###

使用 postman 验证请求，访问 `http://localhost:8080/test/valid` 这个接口。如下图所示：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMTI0MTA3MzM_size_16_color_FFFFFF_t_70_pic_center]  
服务器返回的错误信息如下：

{ 
        "timestamp": "2020-11-25T05:02:31.161+0000",
        "status": 400,
        "error": "Bad Request",
        "errors": [
            { 
                "codes": [
                    "NotBlank.orderQueryRequest.orderId",
                    "NotBlank.orderId",
                    "NotBlank.java.lang.String",
                    "NotBlank"
                ],
                "arguments": [
                    { 
                        "codes": [
                            "orderQueryRequest.orderId",
                            "orderId"
                        ],
                        "arguments": null,
                        "defaultMessage": "orderId",
                        "code": "orderId"
                    }
                ],
                "defaultMessage": "order id must not be null",
                "objectName": "orderQueryRequest",
                "field": "orderId",
                "rejectedValue": null,
                "bindingFailure": false,
                "code": "NotBlank"
            },
            { 
                "codes": [
                    "NotBlank.orderQueryRequest.orderStatus",
                    "NotBlank.orderStatus",
                    "NotBlank.java.lang.String",
                    "NotBlank"
                ],
                "arguments": [
                    { 
                        "codes": [
                            "orderQueryRequest.orderStatus",
                            "orderStatus"
                        ],
                        "arguments": null,
                        "defaultMessage": "orderStatus",
                        "code": "orderStatus"
                    }
                ],
                "defaultMessage": "order status must not be null",
                "objectName": "orderQueryRequest",
                "field": "orderStatus",
                "rejectedValue": null,
                "bindingFailure": false,
                "code": "NotBlank"
            }
        ],
        "message": "Validation failed for object='orderQueryRequest'. Error count: 2",
        "path": "/test/valid"
    }

当然，如果你觉得返回的错误信息不够友好，可以使用 Spring MVC 的统一异常处理。这个也挺简单的，大家在网上可以搜索一下。这个不在今天的讨论范畴。

今天主要是想给大家分享一下如何使用自定义注解来进行请求参数只是一个枚举类里面的值这种方式的校验。比如就是上面的订单状态这个请求参数。假设这个值在我们订单系统里面有以下几个值：

*  0 ：订单初始化
 *  1 ：订单成功
 *  2 ：订单失败

首先我们定义一个枚举类来保存这几个状态：

@AllArgsConstructor
    @Getter
    public enum OrderStatusEnum implements EnumBase<String> { 
        
        INIT("0", "订单初始化"),
        SUCCESS("1", "订单成功"),
        FAIL("2", "订单失败"),
        ;
    
        private String code;
        
        private String message;
        
        public static OrderStatusEnum getByCode(String code) { 
            for (OrderStatusEnum orderStatusEnum : OrderStatusEnum.values()) { 
                if(orderStatusEnum.getCode().equals(code)){ 
                    return orderStatusEnum;
                }
            }
            return null;
        }
    
    }
    
    // 枚举基础接口
    public interface EnumBase<T> { 
    
        T getCode();
    
        String getMessage();
    
    }

我们如何来进行这种方式的值的校验呢。下面我来分享一下我对这种类型值的验证的几个阶段。

## 2、版本一 ##

最开始的逻辑就是在业务代码里面进行校验。

OrderStatusEnum orderStatusEnum = OrderStatusEnum.getByCode(orderStatus);
    if(orderStatusEnum == null) { 
    	throw new RuntimeException("not support order status : " + orderStatus);
    }

这种方式是比较简单的，但是这种校验逻辑是散落在各个业务代码里面，不够集中，不够优雅。

## 3、版本二 ##

使用了 hibernate 的自定义注解来定义有效值的集合。

### 3.1 ValidValue.java ###

定义一个自定义注解，value 里面包含所有的有效值，通过类 ValidValueValidator 实现。并且定义了方法 `canNull` 来判断标注这个注解的属性是否能够传递空值。

@Target({  FIELD})
    @Retention(RUNTIME)
    @Constraint(validatedBy = ValidValueValidator.class)
    @Documented
    public @interface ValidValue { 
    
        String[] value() default { };
    
        String message() default "invalid value";
    
        Class<?>[] groups() default { };
    
        boolean canNull() default false;
    
        Class<? extends Payload>[] payload() default { };
    
        @Target({  METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
        @Retention(RUNTIME)
        @Documented
        @interface List { 
            ValidValue[] value();
        }
    
    }

### 3.2 ValidValueValidator.java ###

ValidValueValidator 类实现了 hibernate-validator 的扩展接口 ConstraintValidator 。`initialize` 方法可以通过获取注解上面的值进行初始化。然后`isValid` 就是对标注检验注解的参数进行校验。如果返回 false 就表示验证不通过，返回 true 就是校验通过。

public class ValidValueValidator implements ConstraintValidator<ValidValue, String> { 
    
        private String[] validValues;
    
        private boolean canNull;
    
        @Override
        public void initialize(ValidValue constraintAnnotation) { 
            validValues = constraintAnnotation.value();
            canNull = constraintAnnotation.canNull();
        }
    
        @Override
        public boolean isValid(String value, ConstraintValidatorContext context) { 
            if(StringUtils.isBlank(value)){ 
                if(canNull) { 
                    return true;
                } else { 
                    return false;
                }
            }
            if(ArrayUtils.isEmpty(validValues)){ 
                return false;
            }
            for (String validValue : validValues) { 
                if(StringUtils.equals(validValue, value)){ 
                    return true;
                }
            }
            return false;
        }
    }

### 3.3 验证 ###

OrderQueryRequest 类的 orderStatus 属性上面添加 `@ValidValue`，并指定有效值是`{"0", "1", "2"}`。

使用 postman 验证请求，访问 `http://localhost:8080/test/valid` 这个接口。传递合法的值就会成功响应，如下图所示：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMTI0MTA3MzM_size_16_color_FFFFFF_t_70_pic_center 1]  
如果传递不符合的值，就会报错，比如请求参数如下：

{ 
        "merchantId" : "123456",
        "orderId" : "123456",
        "orderStatus" : "5"
    }

响应的参数如下所示：

{ 
        "timestamp": "2020-11-25T13:21:04.485+0000",
        "status": 400,
        "error": "Bad Request",
        "errors": [
            { 
                "codes": [
                    "ValidValue.orderQueryRequest.orderStatus",
                    "ValidValue.orderStatus",
                    "ValidValue.java.lang.String",
                    "ValidValue"
                ],
                "arguments": [
                    { 
                        "codes": [
                            "orderQueryRequest.orderStatus",
                            "orderStatus"
                        ],
                        "arguments": null,
                        "defaultMessage": "orderStatus",
                        "code": "orderStatus"
                    },
                    false,
                    [
                        "0",
                        "1",
                        "2"
                    ]
                ],
                "defaultMessage": "not support order status : 5",
                "objectName": "orderQueryRequest",
                "field": "orderStatus",
                "rejectedValue": "5",
                "bindingFailure": false,
                "code": "ValidValue"
            }
        ],
        "message": "Validation failed for object='orderQueryRequest'. Error count: 1",
        "path": "/test/valid"
    }

但是这种情况也是有局限性的，如果一个枚举的值有很多那么就需要把所有的参数都列表出来。这一点对于使用值来说不太友好。

## 4、版本三 ##

这种情况我们就可以把需要的枚举添加到自定义注解的方法当中。因为我们的枚举实现了接口 EnumBase，而我们可以通过接口的 `getCode()` 方法获取到枚举的类型值然后再和传入的参数进行比较。这样就是面向接口编程的好处。

> EnumBase.java

public interface EnumBase<T> { 
    
        T getCode();
    
        String getMessage();
    
    }

### 4.1 EnableEnum.java ###

定义注解 `@EnableEnum`，value 值是 EnumBase 接口的实现类，并且是一个枚举类。然后通过 `EnableEnumValidator` 类来进行枚举值验证。

@Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.FIELD)
    @Documented
    @Constraint(validatedBy = EnableEnumValidator.class)
    public @interface EnableEnum { 
    
        Class<? extends EnumBase> value();
    
        String message() default "invalid value";
    
        Class<?>[] groups() default {  };
    
        Class<? extends Payload>[] payload() default { };
    
        @Target({  METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
        @Retention(RUNTIME)
        @Documented
        @interface List { 
            EnableEnum[] value();
        }
    
    }

### 4.2 EnableEnumValidator.java ###

初始化 `enumBaseClazz` 传入的枚举类 class。获取这个枚举类里面的所有常量与需要验证的参数一一对比，如果能够与其中的一个参数进行匹配那么就验证通过。否则就验证失败。

public class EnableEnumValidator implements ConstraintValidator<EnableEnum, String> { 
    
        private Class<? extends EnumBase> enumBaseClazz;
    
        @Override
        public void initialize(EnableEnum constraintAnnotation) { 
            enumBaseClazz = constraintAnnotation.value();
        }
    
        @Override
        public boolean isValid(String value, ConstraintValidatorContext context) { 
            if(enumBaseClazz == null) { 
                return false;
            }
            if(enumBaseClazz.isInterface() || Modifier.isAbstract(enumBaseClazz.getModifiers())){ 
                return false;
            }
            if(!enumBaseClazz.isEnum()){ 
                return false;
            }
            if(StringUtils.isBlank(value)){ 
                return false;
            }
            EnumBase[] enumConstants = enumBaseClazz.getEnumConstants();
            for (EnumBase enumConstant : enumConstants) { 
                if(enumConstant.getCode().equals(value)){ 
                    return true;
                }
            }
            return false;
        }
    
    }

### 3.3 验证 ###

把请求类修改成下面：

使用 postman 进行请求同样能够达到版本二的结果，但是需要填写的参数就比较少了。

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMTI0MTA3MzM_size_16_color_FFFFFF_t_70_pic_center]: /images/20221120/9d12b5fa1db9490bb8b0853864f97584.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMTI0MTA3MzM_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20221120/7a790dc7412a4504880659e679995277.png