确保数据安全！使用Spring Boot 实现强大的API参数验证

我们在项目开发中，出于对数据完整性的考虑，基本上每个接口都需要参数校验，参数校验可以自己手动校验，也可以用工具校验，今天松哥和大家分享如何利用 Spring Boot 自带的工具实现参数校验。

一 前端 or 后端？

参数校验应该在前端完成还是后端完成？

正常来说，前后端都是需要校验的，但是前后端校验的目的各不相同。

一般来说，前端校验可以满足两个需求：

1. 用户体验：前端校验可以即时反馈给用户，减少等待服务器响应的时间，提高用户体验。
2. 减轻服务器负担：通过前端校验可以过滤掉一些明显无效的请求，减少不必要的服务器负载。

真正要确保数据完整性，还得要靠后端，后端校验可以起到如下作用：

1. 安全性：由于前端代码可以被绕过或修改。后端校验是安全的必要保障，确保即使前端校验被绕过，数据的安全性和完整性也能得到保证。
2. 数据一致性：后端校验可以确保所有通过的请求都符合业务逻辑和数据模型的要求，保持数据的一致性。
3. 容错性：后端校验可以处理那些前端未能覆盖到的异常情况，作为最后一道防线。
4. 跨平台一致性：后端校验确保了无论用户通过何种客户端（Web、移动应用、第三方 API 等）访问服务，数据校验的标准都是一致的。
5. 维护和可扩展性：后端校验逻辑通常更容易维护和更新，因为它们集中在服务器端，而不是分散在多个客户端。
6. 日志和监控：后端可以记录校验失败的请求，这对于监控系统安全和进行问题诊断非常有用。

因此，后端校验才能真正确保数据的完整性，今天松哥也是要和大家聊一聊后端数据校验。

二 参数校验注解

2.1 参数校验依据

在 Spring Boot 中，数据校验是通过 JSR303/JSR380 规范的 Bean Validation 实现的。

这里涉及到两个概念，松哥和大家简单说下。

JSR303 是 Bean Validation 的 1.0 版本，正式名称为《Bean Validation》。它提供了一套注解和 API 来定义 Java 对象（Bean）的验证规则。这些注解可以直接用于 Bean 的属性上，以声明式的方式定义验证逻辑。JSR303 定义了一组标准的验证注解，如 @NotNull、@Size、@Email 等，用于校验对象的属性是否满足特定的条件。

而 JSR380 则是 Bean Validation 的 2.0 版本，也称为《Jakarta Bean Validation 2.0》。随着 JavaEE 向 JakartaEE 的迁移，JSR380 成为了新的规范。JSR380 在 JSR303 的基础上进行了扩展和改进，增加了新的注解、改进了 API，并提供了更好的集成方式。JSR380 的注解与 JSR303 兼容，但增加了一些新的注解，如 @Email 的 message 属性支持国际化，以及 @PositiveOrZero、@NegativeOrZero 等。

松哥下面案例主要和小伙伴们分享最新的 JSR380 规范中的参数校验注解。

2.2 代码实践

现在我们创建一个 Spring Boot 项目，使用当前最新版，并且引入参数校验依赖，最终创建好的工程依赖如下：

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

假设我现在有一个 UserDto 类，需要进行参数校验，那么我可以按照如下方式定义 UserDto：

/**
 * @author：江南一点雨
 * @site：http://www.javaboy.org
 * @微信公众号：江南一点雨
 * @github：https://github.com/lenve
 * @gitee：https://gitee.com/lenve
 */
public class UserDto {
    @NotNull(message = "用户名不能为空")
    private String username;
    @NotBlank(message = "密码不能为空")
    private String password;
    @NotEmpty(message = "邮箱不能为空")
    private String email;
    //省略 getter/setter


    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

接下来在 Controller 的方法参数前使用 @Validated 注解来开启校验。

/**
 * @author：江南一点雨
 * @site：http://www.javaboy.org
 * @微信公众号：江南一点雨
 * @github：https://github.com/lenve
 * @gitee：https://gitee.com/lenve
 */
@RestController
public class UserController {
    @GetMapping("/hello")
    public String hello(@Validated UserDto userDto, BindingResult bindingResult) {
        if (bindingResult.hasErrors()) {
            // 处理校验失败情况
        }
        return "200";
    }
}

当参数校验失败时，会抛出 MethodArgumentNotValidException 异常。可以在全局异常处理器中捕获该异常并进行统一处理。

/**
 * @author：江南一点雨
 * @site：http://www.javaboy.org
 * @微信公众号：江南一点雨
 * @github：https://github.com/lenve
 * @gitee：https://gitee.com/lenve
 */
@RestControllerAdvice
public class GlobalException {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public String handleValidationExceptions(MethodArgumentNotValidException ex) {
        // 获取校验结果的错误信息
        String message = ex.getBindingResult().getAllErrors().get(0).getDefaultMessage();
        return message;
    }
}

如此就大功告成了～是不是非常 Easy？

2.3 异常提示优化

上面参数校验注解中的异常提示都是在 Java 代码里边硬编码的，我们也可以提前定义好异常提示文本，然后在代码里引用即可，这样更加方便，也好维护。

在 Spring Boot 项目中，可以通过在 messages.properties 文件中定义异常提示文本，并在代码中通过 @Message 注解引用这些文本来实现国际化和自定义错误消息。

具体步骤是这样的：

1. 创建 messages.properties 文件：在 src/main/resources 目录下创建一个 messages.properties 文件（对于不同语言版本，可以创建如 messages_en.properties、messages_fr.properties 等文件）。
2. 定义异常提示文本：在 messages.properties 文件中定义键值对，键用于在代码中引用，值是实际的错误消息。

NotEmpty.username=用户名不能为空
NotBlank.password=密码不能为空
Email.email=邮箱格式不正确

3. 在实体类或 DTO 上使用校验注解。

import javax.validation.constraints.Email;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import org.hibernate.validator.constraints.NotEmpty;

public class UserDto {
    @NotNull(message = "{NotEmpty.username}")
    private String username;
    
    @NotBlank(message = "{NotBlank.password}")
    private String password;
    
    @Email(message = "{Email.email}")
    private String email;

    // Getters and setters
}

4. 配置国际化：如果你的应用需要支持多语言，可以在 application.properties 或 application.yml 中配置消息源。

spring.messages.basename=messages
spring.messages.encoding=UTF-8

这样，当校验失败时，Spring 将自动从 messages.properties 文件中查找对应的错误消息，并将其返回给客户端。这种方法不仅可以使错误消息更加灵活和可维护，还可以方便地实现国际化。

三 什么是分组校验

为什么需要分组校验呢？

假设我们有一个用户实体 User，它包含用户名、密码和邮箱三个字段。在用户注册时，我们需要校验用户名和密码非空，邮箱格式正确。但在用户信息更新时，我们只需要校验用户名和邮箱，密码可能不会被修改，因此不需要校验。对于这种需求，我们可以使用分组校验来实现这一需求。

松哥通过一个具体的案例来和小伙伴们演示下。

首先，我们定义两个校验分组，一个用于注册，一个用于更新：

public interface RegisterGroup {}
public interface UpdateGroup {}

分组其实就是两个空接口，用来做标记用。

然后，我们在 User 实体上应用这些分组：

import javax.validation.constraints.Email;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;

public class User {
    @NotBlank(message = "用户名不能为空", groups = {RegisterGroup.class, UpdateGroup.class})
    private String username;

    @NotBlank(message = "密码不能为空", groups = RegisterGroup.class)
    private String password;

    @Email(message = "邮箱格式不正确", groups = {RegisterGroup.class, UpdateGroup.class})
    private String email;

    // Getters and setters
}

上面代码中，username 和 email 即属于注册分组也属于更新分组，而 password 则只属于注册分组。

接下来，在注册接口中，我们使用 @Validated 注解并指定 RegisterGroup 分组：

/**
 * @author：江南一点雨
 * @site：http://www.javaboy.org
 * @微信公众号：江南一点雨
 * @github：https://github.com/lenve
 * @gitee：https://gitee.com/lenve
 */
@RestController
public class UserController {
    @GetMapping("/hello")
    public String hello(@Validated UserDto userDto, BindingResult bindingResult) {
        if (bindingResult.hasErrors()) {
            // 处理校验失败情况
        }
        return "200";
    }

    @PostMapping("/register")
    public String register(@Validated(RegisterGroup.class) @RequestBody UserDto user) {
        // 注册逻辑
        return "注册成功";
    }

    @PostMapping("/update")
    public String update(@Validated(UpdateGroup.class) @RequestBody UserDto user) {
        // 更新逻辑
        return "更新成功";
    }
}

在这个例子中，当调用注册接口时，User 对象会根据 RegisterGroup 分组进行校验，而调用更新接口时，则会根据 UpdateGroup 分组进行校验。这样，我们就可以根据不同的业务需求来应用不同的校验规则了。

分组校验这种方式提供了一种灵活的方式来应对不同的校验场景，使得我们的代码更加清晰和易于维护。

四 校验注解

上面松哥和大家演示了几个常用的参数校验注解，完整的校验注解如下：

分类	注解	作用说明
空值检查	@Null	验证对象必须为 null
	@NotNull	验证对象不能为 null
	@NotEmpty	验证对象非 null，且字符串和数组的 length、Collection 和 Map 的 size 大于 0
	@NotBlank	字符串不能为 null 且至少有一个非空字符
Boolean 检查	@AssertTrue	验证 boolean 类型值为 true
	@AssertFalse	验证 boolean 类型值为 false
长度检查	@Size(max, min)	验证对象（字符串、集合、数组）长度是否在指定范围之内
日期检查	@Past	验证日期必须是一个过去的日期
	@Future	验证日期必须是一个将来的日期
数值检查	@Min(value)	验证数字的大小是否大于等于指定的值
	@Max(value)	验证数字的大小是否小于等于指定的值
	@DecimalMin(value)	验证数字的大小是否大于等于指定的值，小数存在精度
	@DecimalMax(value)	验证数字的大小是否小于等于指定的值，小数存在精度
	@Digits(integer, fraction)	验证数字是否符合指定格式，整数部分精度不能超过 integer，小数部分精度不能超过 fraction
	@Positive	验证数字必须为正数
	@Negative	验证数字必须为负数
	@PositiveOrZero	验证数字必须为正数或零
	@NegativeOrZero	验证数字必须为负数或零
其它检查	@Email	验证字符串是否符合电子邮件地址的格式
	@Pattern(regexp)	验证字符串是否符合正则表达式的规则

好啦，这就是松哥和大家介绍的参数校验～公众号后台回复 20241101 可以获取本文完整案例。