SpringBoot 的优雅的接口参数验证

一时失言乱红尘 2023-10-15 10:08 100阅读 0赞

# 1. 为什么需要参数验证 #

在应用程序的开发中，我们经常会遇到需要保证传入参数的正确性的情况。例如，当我们在注册用户时，需要验证用户填写的表单数据是否符合规范，是否缺少必填字段，或者格式是否正确，等等。如果不对参数进行验证，我们的应用程序可能会因此受到攻击或者运行出错。

为了保证参数的正确性，我们需要使用参数验证机制，来检测并处理传入的参数格式是否符合规范。

# 2. 如何进行参数验证 #

Spring Boot内置了一个很强大的参数验证框架——JSR 303 Bean Validation 标准，它可以对我们的实体类参数进行校验，并且可以给我们提供详细的错误提示信息。

具体步骤如下：

# 1. 添加依赖 #

在 pom.xml 文件中添加以下依赖：

xml复制代码
    <dependency>
        <groupId>javax.validation</groupId>
        <artifactId>validation-api</artifactId>
        <version>2.0.1.Final</version>
    </dependency>
    
     
    <dependency>
        <groupId>org.hibernate.validator</groupId>
        <artifactId>hibernate-validator</artifactId>
        <version>6.1.5.Final</version>
    </dependency>

# 2. 在实体类中添加参数验证注解 #

java复制代码public class User {
        @NotNull(message="用户名不能为空")
        private String username;
        
        @NotNull(message="密码不能为空")
        @Size(min=6, max=20, message="密码长度应该在6到20位")   
        private String password;
        
        // getter 和 setter 方法
    }

在实体类中使用注解，如上代码所示，可以指定当前字段是否可以为 null，以及字符串的长度和格式等信息，如果传入的参数不符合预定的规则，在校验时就会产生相应的提示。

常用的参数验证注解：

*  @NotNull：验证注解的元素值不为null；
 *  @NotEmpty：验证注解的元素值不为null，且String类型也不为 ""；
 *  @NotBlank：验证注解的元素值不为null，且允许去除两端空格后不为空；
 *  @Size：验证注解的元素值长度在min和max范围内；
 *  @Digits：验证注解元素值的整数位数和小数位数是否符合预期；
 *  @Range：验证注解元素值的大小是否在指定范围内；
 *  @Email：验证注解的元素值是否为Email格式。

# 3. 在Controller中加入对参数的验证 #

java复制代码@RestController
    @RequestMapping("/user")
    public class UserController {
        
        @PostMapping("/register")
        public CommonResult<User> register(@RequestBody @Validated User user) {
            return CommonResult.success(user);
        }
    }

在Controller层进行参数校验时，加上 @Validated 注解以告诉Spring进行参数校验，@RequestBody 注解用于将请求体中的JSON数据绑定到实体类中。

# 4. 定义全局异常处理器，并定义返回结果CommonResult #

java复制代码@RestControllerAdvice
    public class GlobalExceptionHandler {
    
        @ExceptionHandler(value = MethodArgumentNotValidException.class)
        public CommonResult<Object> handleMethodArgumentNotValidException(MethodArgumentNotValidException ex){
            List<ObjectError> errors = ex.getBindingResult().getAllErrors();
            StringBuilder errorMsg = new StringBuilder();
            errors.forEach(error -> errorMsg.append(error.getDefaultMessage()).append("; "));
            return CommonResult.fail(ResultCode.PARAM_VALID_ERROR.getCode(), errorMsg.toString(), null);
        }
    
        @ExceptionHandler(value = Exception.class)
        public CommonResult<Object> handleException(Exception ex){
            log.error("系统发生异常：", ex);
            return CommonResult.fail(ResultCode.SYSTEM_ERROR.getCode(), ResultCode.SYSTEM_ERROR.getMsg(), null);
        }
    }

在上述代码中，我们定义了两个异常处理方法，一个处理 MethodArgumentNotValidException 异常，一个处理其他类型的异常，使用了 @ExceptionHandler 注解将不同类型的异常映射到不同的处理方法中。

java复制代码public enum ResultCode {
        SUCCESS(200, "操作成功"),
        PARAM_VALID_ERROR(400, "参数校验失败"),
        UNAUTHORIZED(401, "未认证"),
        FORBIDDEN(403, "无权限"),
        SYSTEM_ERROR(500, "服务器内部错误");
    
        private int code;
        private String msg;
    
        ResultCode(int code, String msg) {
            this.code = code;
            this.msg = msg;
        }
    
        public int getCode() {
            return code;
        }
    
        public String getMsg() {
            return msg;
        }
    }
    
    public class CommonResult<T> {
        private int code;
        private String msg;
        private T data;
    
        public CommonResult() {}
    
        public CommonResult(int code, String msg, T data) {
            this.code = code;
            this.msg = msg;
            this.data = data;
        }
    
        public static <T> CommonResult<T> success(T data) {
            return new CommonResult<T>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMsg(), data);
        }
    
        public static <T> CommonResult<T> fail(ResultCode resultCode) {
            return new CommonResult<T>(resultCode.getCode(), resultCode.getMsg(), null);
        }
    
        public static <T> CommonResult<T> fail(ResultCode resultCode, T data) {
            return new CommonResult<T>(resultCode.getCode(), resultCode.getMsg(), data);
        }
    
        // getter 和 setter 方法
    }

在上述代码中，我们使用泛型和枚举类定义各种操作返回的枚举值，通过封装返回值，返回给前端统一的返回格式，减少重复代码。

# 5. 通过Postman模拟测试参数验证 #

我们将请求方式设置为 POST，并将请求的 URL 设置为 http://localhost:8080/user/register。另外，我们还需要设置请求头的 Content-Type 为 application/json。

我们传入了一个用户名为 user ，密码为 123 的用户并进行请求，这个请求在参数校验的过程中会出现异常。

最终的打印结果为：

json复制代码{
        "code": 400,
        "msg": "密码长度应该在6到20位; ",
        "data": null
    }

# 3.自定义注解和验证器 #

在实体类中使用注解进行参数验证，这种方式非常简单快捷，但对于一些复杂的逻辑验证可能不够灵活。我们也可以采用编写自定义注解和验证器的方式进行参数验证。

比如，我们可以编写自定义注解 @Age 和验证器 AgeValidator，使用这两个自定义类对请求参数进行验证，示例代码如下：

java复制代码@Target({ElementType.FIELD, ElementType.PARAMETER})
    @Retention(RetentionPolicy.RUNTIME)
    @Documented
    @Constraint(validatedBy = {AgeValidator.class})
    public @interface Age {
        String message() default "年龄不在合法范围内";
        int minAge() default 0;
        int maxAge() default 150;
        Class<?>[] groups() default {};
        Class<? extends Payload>[] payload() default {};
    }
    
    public class AgeValidator implements ConstraintValidator<Age, Integer> {
        
        private int minAge;
        private int maxAge;
    
        @Override
        public void initialize(Age constraintAnnotation) {
            this.minAge = constraintAnnotation.minAge();
            this.maxAge = constraintAnnotation.maxAge();
        }
    
        @Override
        public boolean isValid(Integer value, ConstraintValidatorContext context) {
            if(value == null) {
                return true; // 允许为空值
            }
            if(value < minAge || value > maxAge) {
                return false; // 验证不通过
            }
            return true; // 验证通过
        }
    }
    
    public class User {
        @NotNull(message="用户名不能为空")
        private String username;
        
        @Age(message="年龄不在合法范围内", minAge=0, maxAge=120)
        private Integer age;
        
        // getter 和 setter 方法
    }

如上代码展示了如何使用自定义注解和验证器进行参数验证，使用自定义注解时，我们可以指定年龄的最小值和最大值，并使用 AgeValidator 在实体类中对年龄进行验证。

# 4.小结 #

使用参数验证机制可以有效地提高我们应用程序的健壮性和安全性，同时也可以节省我们进行参数校验的时间和精力。Spring Boot 内置的参数验证框架 JSR 303 Bean Validation 标准可以帮助我们简单快速地完成参数校验，结合全局异常处理器和自定义的响应结果类，我们可以快速反馈请求信息的正确性，并在出现错误时提供详细的错误提示信息，非常方便实用。