首页 > 软件编程 > java > Spring Boot Validation 接口校验

从零到掌握Spring Boot Validation 接口校验的详细过程

2025-02-25 15:54:51 作者：库库林_沙琪马

本文详细介绍了SpringBoot的Validation接口校验机制,包括其核心功能、常用注解、自定义校验、以及实际应用场景,通过注解定义数据校验规则,感兴趣的朋友跟随小编一起看看吧

在开发 Web 应用时，数据校验是不可忽视的一部分。无论是注册用户信息、提交表单数据，还是处理业务逻辑，数据的有效性和完整性都需要得到保证。Spring Boot 提供了强大的验证功能，基于 Hibernate Validator 框架，通过注解方式简化了数据校验的实现。本文将详细介绍 Spring Boot 的 Validation 接口校验机制，包括其核心功能、常用注解、自定义校验、以及实际应用场景。

1. 什么是 Spring Validation？

Spring Validation 是一个用于数据校验的框架，它基于 JSR-303（Bean Validation API） 和 Hibernate Validator 实现。通过在 JavaBean 的字段上添加特定的注解，可以定义数据的校验规则。Spring Boot 通过整合 Hibernate Validator，使得在 Web 应用中使用数据校验变得更加简单。

2. Spring Boot Validation 的核心功能

注解式校验：通过注解定义数据校验规则。
自动化校验：Spring Boot 提供了对校验的自动支持，无需手动编写校验逻辑。
异常处理：Spring Boot 可以自动将校验失败的错误信息返回给客户端。
支持分组校验：可以为不同的场景定义不同的校验分组。
支持自定义校验：可以扩展注解，定义自定义的校验逻辑。

3. 常用的校验注解

以下是 Spring Boot 中常用的校验注解：

注解	功能描述
`@NotNull`	确保字段不为 null
`@Null`	确保字段为 null
`@NotBlank`	确保字段不为空（字符串）
`@NotEmpty`	确保字段不为空（集合、数组）
`@Length`	确保字段的长度在指定范围内
`@Size`	确保字段的长度在指定范围内（适用于集合、数组、字符串）
`@Range`	确保字段的值在指定范围内
`@Min`	确保字段的值大于等于指定值
`@Max`	确保字段的值小于等于指定值
`@Email`	确保字段为有效的电子邮件地址
`@Pattern`	确保字段的值匹配指定的正则表达式
`@Past`	确保字段的值是过去的日期
`@Future`	确保字段的值是未来的日期

4. Spring Boot Validation 的实现步骤

步骤 1：添加依赖

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

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

步骤 2：创建 JavaBean

创建一个需要校验的 JavaBean 类，并在字段上添加校验注解：

import jakarta.validation.constraints.*;
public class User {
    @NotNull(message = "用户名不能为空")
    @Size(min = 2, max = 10, message = "用户名长度必须在2到10之间")
    private String username;
    @NotNull(message = "密码不能为空")
    @NotBlank(message = "密码不能为空")
    @Pattern(regexp = "^(?=.*\\d)(?=.*[A-Za-z])(?=.*[@$!%*#?&])[A-Za-z\\d@$!%*#?&]{8,20}$", message = "密码格式不正确")
    private String password;
    @Email(message = "邮箱格式不正确")
    private String email;
    @Min(value = 18, message = "年龄必须大于等于18岁")
    private Integer age;
    public User() {}
    // Getters and Setters
}

步骤 3：在控制器中使用 @Valid 注解

在控制器的参数中使用 @Valid 注解启用校验：

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotNull;
@RestController
public class UserController {
    @PostMapping("/register")
    public ResponseEntity<?> register(@Valid @RequestBody User user) {
        // 业务逻辑
        return ResponseEntity.ok("注册成功");
    }
}

步骤 4：处理校验异常

Spring Boot 会自动将校验失败的错误信息封装到 MethodArgumentNotValidException 异常中。可以通过全局异常处理来统一返回错误信息：

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import jakarta.validation.ConstraintViolation;
import jakarta.validation.ConstraintViolationException;
import java.util.HashMap;
import java.util.Map;
@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidationExceptions(MethodArgumentNotValidException ex) {
        Map<String, String> 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);
    }
}

5. 自定义校验注解

如果内置的校验注解无法满足需求，可以通过自定义注解来扩展校验功能。

自定义校验注解

import jakarta.validation.Constraint;
import jakarta.validation.Payload;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Documented
@Constraint(validatedBy = {PhoneValidator.class})
@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Phone {
    String message() default "手机号格式不正确";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

自定义校验逻辑

import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;
public class PhoneValidator implements ConstraintValidator<Phone, String> {
    @Override
    public void initialize(Phone constraintAnnotation) {
    }
    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if (value == null) {
            return false;
        }
        // 手机号正则表达式
        String regex = "^1(3\\d|5[i-o]\\d|78\\d|4\\d)\\d{7}$";
        return value.matches(regex);
    }
}

使用自定义校验注解

@Phone(message = "手机号格式不正确")
private String phone;

6. 分组校验和条件校验

分组校验

通过分组校验，可以为不同的场景定义不同的校验规则。

public interface SaveGroup {
}
public interface UpdateGroup {
}
@NotNull(groups = SaveGroup.class)
@Size(min = 2, max = 10, groups = {SaveGroup.class, UpdateGroup.class})
private String username;

在控制器中指定需要校验的分组：

@PostMapping("/save")
public ResponseEntity<?> save(@Validated(SaveGroup.class) @RequestBody User user) {
    // 业务逻辑
    return ResponseEntity.ok("保存成功");
}

条件校验

通过 @ScriptAssert 注解，可以基于脚本语言（如 JavaScript 或 Groovy）实现复杂的条件校验。

@ScriptAssert(lang = "javascript", script = "password.length >= 8 && password.match(/^(?=.*\\d)(?=.*[A-Za-z])(?=.*[@$!%*#?&])[A-Za-z\\d@$!%*#?&]{8,20}$/)")
public class User {
    // 字段定义
}

7. 结合其他技术

1. 统一异常处理

通过全局异常处理，可以统一返回校验失败的错误信息，提升用户体验。

2. 日志记录

通过 AOP（Aspect Oriented Programming），可以记录校验失败的日志，方便后续分析：

@Aspect
@Component
public class ValidationAspect {
    @Around("execution(* *(..)) && @annotation(org.springframework.web.bind.annotation.PostMapping)")
    public Object logAround(ProceedingJoinPoint joinPoint) throws Throwable {
        try {
            Object[] args = joinPoint.getArgs();
            if (args != null && args.length > 0) {
                for (Object arg : args) {
                    if (arg != null && arg.getClass().getAnnotation(Valid.class) != null) {
                        // 记录日志
                        System.out.println("开始校验数据：" + arg);
                    }
                }
            }
            return joinPoint.proceed();
        } catch (MethodArgumentNotValidException ex) {
            // 记录校验失败的日志
            System.out.println("校验失败：" + ex.getBindingResult());
            throw ex;
        }
    }
}

8. 常见问题和解决方案

常见问题

校验注解不生效：
- 检查是否添加了 spring-boot-starter-validation 依赖。
- 确保在控制器中使用了 @Valid 注解。
错误信息不返回：
- 检查是否实现了全局异常处理。
- 确保控制器的返回类型为 ResponseEntity。
自定义校验注解不生效：
- 检查自定义注解的 ConstraintValidator 是否正确实现。
- 确保自定义注解使用了 @Constraint 注解。

总结

Spring Boot 的 Validation 功能提供了一种简单而强大的数据校验方式，通过注解式校验和自动化处理，能够显著提升开发效率和代码质量。结合 Hibernate Validator 的强大功能，开发者可以轻松实现复杂的校验逻辑，同时通过自定义校验注解和分组校验，满足不同的业务需求。

希望本文能帮助你在实际项目中更好地使用 Spring Boot 的 Validation 功能，提高代码的健壮性和用户体验！

到此这篇关于从零到掌握Spring Boot Validation 接口校验的详细过程的文章就介绍到这了,更多相关Spring Boot Validation 接口校验内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！