摘要：在当今的互联网软件开发领域，构建稳定、可靠且高效的 RestFul 接口是至关重要的环节。而对接口参数进行有效的校验，则是保障系统稳健运行、防止非法数据流入的关键防线。在 Spring Boot3 框架下，参数校验功能得到了进一步的优化与完善，为开发者提供了便
在当今的互联网软件开发领域，构建稳定、可靠且高效的 RestFul 接口是至关重要的环节。而对接口参数进行有效的校验，则是保障系统稳健运行、防止非法数据流入的关键防线。在 Spring Boot3 框架下，参数校验功能得到了进一步的优化与完善，为开发者提供了便捷且强大的工具。本文将深入探讨在 Spring Boot3 中如何对 RestFul 接口的参数进行校验。
要在 Spring Boot3 项目中开启参数校验功能，首要任务是在项目的 pom.xml 文件中引入 spring-boot-starter-validation 依赖。这一依赖基于强大的 Hibernate Validator 实现，宛如一把万能钥匙，为我们开启了全面且便捷的参数校验大门。在 pom.xml 中添加如下代码：
org.springframework.bootspring-boot-starter-validation添加完成后，Maven 会自动下载并管理该依赖及其相关的所有组件，为后续的参数校验工作筑牢基础。值得注意的是，从 Spring Boot2.3 版本开始，默认的 spring-boot-starter-web 组件不再包含此依赖，需要我们手动引入，以确保参数校验功能的正常使用。
Spring Boot3 为开发者提供了种类繁多的内置校验注解，这些注解犹如工具箱中的各种精密工具，各自具备独特的功能，能够满足多样化的参数校验需求。以下为大家详细介绍一些常用的校验注解：
@NotNull：此注解用于确保参数的值不为空（null）。例如，在用户注册场景中，用户名和密码字段通常不允许为空，此时就可以使用 @NotNull 注解对相应的参数进行标注，以保证数据的完整性。
@NotEmpty：该注解主要用于验证字符串、集合、数组等不为空。比如，在处理用户兴趣标签的接口中，用户的兴趣标签集合不能为空，此时使用 @NotEmpty 注解进行校验，可有效避免空集合带来的潜在问题。
@NotBlank：专门用于验证字符串不能为空且长度必须大于 0，同时会去除字符串前后的空格。在处理用户输入的地址信息时，如果要求地址不能为空且不能仅由空格组成，@NotBlank 注解便是绝佳选择。
@Size：通过此注解可以指定字符串、集合、数组等的长度范围。例如，在设置用户密码时，要求密码长度在 6 - 18 位之间，使用 @Size (min = 6, max = 18) 注解即可轻松实现这一校验规则。
@Min和 **@Max**：分别用于标记数字类型的最小值和最大值。在处理商品价格范围、用户年龄限制等场景时，这两个注解能精准地对数字参数进行范围校验。
@Email：如其名，用于验证字符串是否为合法的邮箱格式。在用户注册或修改邮箱信息时，使用 @Email 注解可确保用户输入的邮箱地址格式正确，避免因格式错误导致的邮件发送失败等问题。
在 Controller 层的接口方法中，我们需要通过特定的注解来触发参数校验流程。Spring Boot3 提供了 @Valid 和 @Validated 注解来实现这一功能。
（一）@Valid 注解
@Valid 注解是 java 标准库提供的，它如同一个启动开关，当请求进入 Controller 层方法时，在参数前添加 @Valid 注解，Spring Boot3 会自动对该参数进行校验。例如，我们有一个处理用户登录的接口，代码如下：
@RestController@RequestMapping("/user")public class UserController {@PostMapping("/login")public String login(@RequestBody @Valid UserLoginDTO userLoginDTO) {// 业务逻辑处理return "登录成功";}}在上述代码中，UserLoginDTO 是一个包含用户名和密码等登录信息的实体类，在 login 方法的参数 userLoginDTO 前添加了 @Valid 注解。这样，当用户发起登录请求时，Spring Boot3 会依据 UserLoginDTO 实体类中定义的校验规则，对传入的参数进行全面检查。
（二）@Validated 注解
@Validated 注解是 Spring 框架提供的，与 @Valid 相比，它具有更强大的功能和更好的集成性。@Validated 不仅可以用在方法参数上进行校验，还支持分组校验功能，这使得它在处理复杂业务场景时展现出更高的灵活性。
例如，在用户注册场景中，可能需要对所有字段进行严格校验；而在用户信息更新时，部分字段可能允许为空或者有不同的校验规则。这时，我们就可以利用 @Validated 的分组校验功能来实现。
首先，定义校验分组接口：
public interface CreateGroup {}public interface UpdateGroup {}然后，在用户实体类的字段注解中指定所属分组：
public class UserDTO {@NotBlank(message = "用户名不能为空", groups = {CreateGroup.class, UpdateGroup.class})private String username;@NotBlank(message = "密码不能为空", groups = {CreateGroup.class})private String password;@Email(message = "邮箱格式不正确", groups = {CreateGroup.class, UpdateGroup.class})private String email;// 其他字段及getter、setter方法}最后，在 Controller 层的方法中使用 @Validated 注解并指定分组：
@RestController@RequestMapping("/user")public class UserController {@PostMapping("/register")public String register(@RequestBody @Validated(CreateGroup.class) UserDTO userDTO) {// 用户注册业务逻辑return "注册成功";}@PutMapping("/update")public String update(@RequestBody @Validated(UpdateGroup.class) UserDTO userDTO) {// 用户信息更新业务逻辑return "更新成功";}}通过这种方式，我们可以根据不同的业务场景，灵活地对参数进行分组校验，大大提高了参数校验的针对性和适应性。
在 Spring Boot 开发中，推荐优先使用 @Validated 注解，因为它能够更好地与 Spring 框架集成，并且在功能上更为强大，尤其是在处理复杂业务逻辑和分组校验需求时，能为开发者带来更高的开发效率和代码的可维护性。
当 Controller 方法接收到请求参数后，会依据定义的校验规则进行参数校验。对于未通过校验规则的非法参数，系统会抛出 MethodArgumentNotValidException.class 异常，并打印出注解中传入的 message 提示信息。然而，默认情况下，这些参数未通过返回的信息格式并不友好，可能会给前端开发人员和用户带来困扰。因此，我们需要通过全局异常捕获机制来处理这些异常，返回更加清晰、友好的提示信息。
在 Spring Boot3 中，实现全局异常捕获非常简单。我们只需创建一个全局异常处理类，并使用 @ControllerAdvice 注解进行标注。以下是一个简单的示例代码：
import org.springframework.http.HttpStatus;import org.springframework.http.ResponseEntity;import org.springframework.web.bind.annotation.ControllerAdvice;import org.springframework.web.bind.annotation.ExceptionHandler;import org.springframework.web.bind.annotation.RestController;import org.springframework.validation.FieldError;import org.springframework.web.bind.MethodArgumentNotValidException;import java.util.HashMap;import java.util.Map;@ControllerAdvice(annotations = RestController.class)public class GlobalExceptionHandler {@ExceptionHandler(MethodArgumentNotValidException.class)public ResponseEntity> handleMethodArgumentNotValidException(MethodArgumentNotValidException ex) {Map errors = new HashMap;ex.getBindingResult.getAllErrors.forEach((error) -> {String fieldName = ((FieldError) error).getField;String errorMessage = error.getDefaultMessage;errors.put(fieldName, errorMessage);});return new ResponseEntity(errors, HttpStatus.BAD_REQUEST);}}在上述代码中，我们定义了一个 GlobalExceptionHandler 类，并使用 @ControllerAdvice 注解将其标记为全局异常处理类。在该类中，通过 @ExceptionHandler 注解捕获 MethodArgumentNotValidException 异常，并对异常信息进行处理。将每个校验失败的字段名和对应的错误信息提取出来，封装到一个 Map 中，并返回给前端。同时，设置 HTTP 状态码为 400（BAD_REQUEST），以表示请求参数有误。通过这种方式，前端开发人员可以清晰地获取到参数校验失败的具体信息，便于快速定位和解决问题，提高了系统的交互性和用户体验。
尽管 Spring Boot3 提供的内置校验注解已经能够满足大多数常见的参数校验需求，但在实际开发中，我们可能会遇到一些特殊的业务场景，这些场景无法通过现有的内置注解来实现精准校验。此时，Spring Boot3 强大的扩展性允许我们自定义校验规则，以满足这些特殊需求。
自定义校验规则通常需要以下几个步骤：
（一）创建自定义校验注解
首先，我们需要定义一个自定义的校验注解。这个注解将用于标记需要进行特定校验的参数。例如，我们要创建一个用于校验手机号码格式的自定义注解，代码如下：
import javax.validation.Constraint;import javax.validation.Payload;import java.lang.annotation.Documented;import java.lang.annotation.Retention;import java.lang.annotation.Target;import static java.lang.annotation.ElementType.FIELD;import static java.lang.annotation.RetentionPolicy.RUNTIME;@Documented@Constraint(validatedBy = MobileValidator.class)@Target({FIELD})@Retention(RUNTIME)public @interface Mobile {String message default "手机号码格式不正确";Class groups default {};Class payload default {};}在上述代码中，我们通过 @Constraint 注解指定了该自定义注解的校验器为 MobileValidator.class。同时，定义了 message 属性用于设置校验失败时的提示信息，groups 属性用于分组校验，payload 属性则用于负载信息传递（通常在高级场景中使用）。
（二）实现自定义校验器
接下来，我们需要实现自定义校验器，即 MobileValidator 类。这个类需要实现 ConstraintValidator 接口，并根据具体的校验逻辑编写 isValid 方法。代码如下：
import javax.validation.ConstraintValidator;import javax.validation.ConstraintValidatorContext;import java.util.regex.pattern;public class MobileValidator implements ConstraintValidator {private static final String MOBILE_REGEX = "^1(3[0-9]|4[5-9]|5[0-35-9]|6[2567]|7[0-8]|8[0-9]|9[0-35-9])\\d{8}$";private Pattern pattern;@Overridepublic void initialize(Mobile constraintAnnotation) {pattern = Pattern.compile(MOBILE_REGEX);}@Overridepublic boolean isValid(String value, ConstraintValidatorContext context) {return value != null && pattern.matcher(value).matches;}}在 initialize 方法中，我们初始化了用于匹配手机号码格式的正则表达式。在 isValid 方法中，通过正则表达式对传入的手机号码字符串进行匹配校验，如果匹配成功则返回 true，否则返回 false。
（三）使用自定义校验注解
完成自定义校验注解和校验器的创建后，我们就可以在实体类中使用自定义校验注解了。例如：
public class UserDTO {@NotBlank(message = "用户名不能为空")private String username;@Mobile(message = "手机号码格式不正确")private String mobile;// 其他字段及getter、setter方法}在上述代码中，我们在 UserDTO 类的 mobile 字段上使用了 @Mobile 自定义校验注解。当对 UserDTO 对象进行参数校验时，系统会自动调用 MobileValidator 校验器对 mobile 字段的值进行校验，确保其符合我们定义的手机号码格式。通过自定义校验，我们能够轻松应对各种特殊的参数校验需求，进一步提升了系统的健壮性和业务适应性。
在 Spring Boot3 开发中，对 RestFul 接口的参数进行校验是确保系统稳定性、安全性和数据准确性的重要环节。通过引入 spring-boot-starter-validation 依赖，我们可以便捷地使用丰富的内置校验注解对参数进行全方位的校验。同时，借助 @Valid 和 @Validated 注解触发校验流程，并通过 @Validated 注解的分组校验功能满足复杂业务场景的需求。此外，通过全局异常捕获机制，我们能够为前端返回友好的错误提示信息，提升系统的交互性和用户体验。对于特殊的业务校验需求，Spring Boot3 还支持自定义校验规则，使得参数校验功能更加灵活和强大。希望本文能够帮助广大互联网软件开发人员深入理解和掌握 Spring Boot3 中 RestFul 接口参数校验的相关知识和技巧，在实际项目开发中构建出更加稳定、可靠的系统。
来源：从程序员到架构师一点号
