当前位置： 首页 > article >正文

Spring Boot Validation 接口校验：从零到掌握

article 2025/2/23 20:54:01

在开发 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 的核心功能

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

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. 常见问题和解决方案

常见问题

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

总结

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

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


http://www.kler.cn/a/557991.html

相关文章：

  • STM32 HAL库I2C函数使用详解：以MPU6050传感器为例
  • Windows 系统下，使用 PyTorch 的 DataLoader 时，如果 num_workers 参数设置为大于 0 的值，报错
  • Apache-CC6链审计笔记
  • PWR电源控制详解教程文章 ~内置初始化驱动代码！！！
  • 网络安全风险事件排名 网络安全事件划分
  • 网络运维学习笔记 012网工初级（HCIA-Datacom与CCNA-EI）某机构新增：GRE隧道与EBGP实施
  • 如何查询网站是否被百度蜘蛛收录？
  • CSS中块级格式化上下文（BFC）详解
  • windwos与linux环境下Iperf3带宽测试工具的安装、使用
  • 集合 数据结构 泛型
  • 【JavaScript】深入理解模块化
  • PHP 性能优化全攻略：提升 Web 应用速度的关键
  • SSH无密登录配置
  • Node.js Buffer 教程
  • Spring Boot （maven）分页4.0.2版本 专业版- 模板化最终版(测试)
  • Git常见面试题
  • 基于ffmpeg+openGL ES实现的视频编辑工具-添加转场（九）
  • /etc/docker/daemon.json这个跟/etc/yum.repos.d/docker-ce.repo这个文件的关系
  • WebXR教学 02 配置开发环境
  • Unity游戏制作中的C#基础（6）方法和类的知识点深度剖析