Spring Boot 参数框架

末蓝、 2023-10-15 10:08 110阅读 0赞

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

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

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

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

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

具体步骤如下：

##### 1. 添加依赖 #####

在 `pom.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. 在实体类中添加参数验证注解 #####

> `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中加入对参数的验证 #####

> `@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 #####

> `@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 注解将不同类型的异常映射到不同的处理方法中。

> `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` 的用户并进行请求，这个请求在参数校验的过程中会出现异常。

最终的打印结果为：

> `{ "code": 400, "msg": "密码长度应该在6到20位; ", "data": null }`

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

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

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

> `@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 标准可以帮助我们简单快速地完成参数校验，结合全局异常处理器和自定义的响应结果类，我们可以快速反馈请求信息的正确性，并在出现错误时提供详细的错误提示信息，非常方便实用。