SpringBoot 的优雅的接口参数验证

2024-02-28 114

版权

本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。

简介： 1. 为什么需要参数验证在应用程序的开发中，我们经常会遇到需要保证传入参数的正确性的情况。例如，当我们在注册用户时，需要验证用户填写的表单数据是否符合规范，是否缺少必填字段，或者格式是否正确，等等。如果不对参数进行验证，我们的应用程序可能会因此受到攻击或者运行出错。为了保证参数的正确性，我们需要使用参数验证机制，来检测并处理传入的参数格式是否符合规范。2. 如何进行参数验证Spring Boot内置了一个很强大的参数验证框架——JSR 303 Bean Validation 标准，它可以对我们的实体类参数进行校验，并且可以给我们提供详细的错误提示信息。

1. 为什么需要参数验证

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

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

2. 如何进行参数验证

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

具体步骤如下：

1. 添加依赖

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

xml复制代码<!-- 添加 JSR-303 Bean Validation 依赖 -->
<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
</dependency>
<!-- Hibernate Validator 的实现 --> 
<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 标准可以帮助我们简单快速地完成参数校验，结合全局异常处理器和自定义的响应结果类，我们可以快速反馈请求信息的正确性，并在出现错误时提供详细的错误提示信息，非常方便实用。