Spring Boot整合Hibernate验证器教程

星夢妙者

发布时间：2025-07-07 16:40:02

956人浏览过

来源于php中文网

原创

spring boot整合hibernate验证器通过添加依赖、定义校验规则、在controller中使用@valid注解、可选全局异常处理、自定义注解、分组校验、嵌套对象校验、错误信息国际化、快速失败模式配置等步骤实现数据校验。1. 添加spring-boot-starter-validation依赖；2. 在实体类或dto中使用@notblank、@size等注解定义规则；3. controller中用@valid触发校验并用bindingresult获取结果；4. 可创建全局异常处理器捕获methodargumentnotvalidexception；5. 自定义注解需创建注解和校验器类并实现constraintvalidator接口；6. 分组校验通过定义分组接口并在注解中指定groups属性；7. 嵌套对象需在属性上加@valid启用校验；8. 国际化通过validationmessages.properties文件配置；9. 快速失败模式通过配置validatorfactory的failfast(true)实现；常见问题包括el依赖缺失、注解未生效、自定义注解无法注入bean等，需分别添加依赖、检查注解使用、注册校验器为bean等方式解决。

Spring Boot整合Hibernate验证器教程

Spring Boot整合Hibernate验证器，主要是为了在你的应用中实现更方便、更强大的数据校验。它利用了Hibernate Validator，这是一个Bean Validation（JSR 380）的参考实现，可以让你通过注解的方式，轻松地对Java Bean的属性进行各种约束校验。

解决方案：

添加依赖： 首先，需要在你的pom.xml文件中加入相应的依赖。Spring Boot通常会自动包含spring-boot-starter-validation，但如果没包含，手动添加一下：
```
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>
```
如果你的项目没有使用Spring Boot，你需要手动添加Hibernate Validator和Bean Validation API的依赖。

定义校验规则： 在你的实体类（Entity）或者DTO（Data Transfer Object）的属性上，使用注解来定义校验规则。例如：

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

public class User {

    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度必须在3到20之间")
    private String username;

    @NotBlank(message = "密码不能为空")
    private String password;

    // Getters and setters
}

这里使用了@NotBlank和@Size注解，分别表示该属性不能为空，且长度必须在3到20之间。message属性可以自定义错误提示信息。

在Controller中使用： 在你的Controller中，使用@Valid注解来触发校验。同时，需要使用BindingResult来获取校验结果。

import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import javax.validation.Valid;

@RestController
public class UserController {

    @PostMapping("/users")
    public String createUser(@Valid @RequestBody User user, BindingResult result) {
        if (result.hasErrors()) {
            // 处理校验失败的情况
            return "校验失败：" + result.getAllErrors().get(0).getDefaultMessage(); // 简化处理，只返回第一个错误信息
        }

        // 处理创建用户的逻辑
        return "用户创建成功";
    }
}

@Valid注解告诉Spring MVC要对User对象进行校验。BindingResult对象包含了校验的结果，可以通过hasErrors()方法判断是否有错误，并通过getAllErrors()方法获取所有的错误信息。

全局异常处理（可选）： 为了更优雅地处理校验失败的情况，可以配置全局异常处理。创建一个全局异常处理器，捕获MethodArgumentNotValidException异常，该异常会在@Valid校验失败时抛出。

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

import java.util.HashMap;
import java.util.Map;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Object> handleValidationExceptions(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(error -> {
            errors.put(error.getField(), error.getDefaultMessage());
        });
        return new ResponseEntity<>(errors, HttpStatus.BAD_REQUEST);
    }
}

这样，当校验失败时，会返回一个包含所有错误信息的JSON响应，方便前端处理。

如何自定义Hibernate Validator的校验注解？

自定义校验注解是Hibernate Validator的强大之处。有时候内置的注解无法满足需求，比如需要校验身份证号码的格式，或者校验某个字段是否在指定的枚举值范围内。

创建注解： 首先，需要创建一个自定义的注解。这个注解需要使用@Constraint注解来指定一个校验器，使用@Target注解来指定注解可以使用的位置（例如字段、方法等），使用@Retention注解来指定注解的生命周期。

import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.*;

@Documented
@Constraint(validatedBy = {MyCustomValidator.class}) // 指定校验器
@Target({ElementType.METHOD, ElementType.FIELD}) // 指定注解可以使用的位置
@Retention(RetentionPolicy.RUNTIME) // 指定注解的生命周期
public @interface MyCustomAnnotation {

    String message() default "自定义校验失败"; // 默认的错误提示信息

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};
}

创建校验器： 接下来，需要创建一个校验器类，实现ConstraintValidator接口。这个接口有两个泛型参数，第一个是自定义注解的类型，第二个是被校验的属性的类型。

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;

public class MyCustomValidator implements ConstraintValidator<MyCustomAnnotation, String> {

    @Override
    public void initialize(MyCustomAnnotation constraintAnnotation) {
        // 初始化方法，可以获取注解的属性
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        // 实现校验逻辑
        if (value == null) {
            return true; // 允许为空
        }
        return value.startsWith("custom"); // 假设校验规则是必须以"custom"开头
    }
}

initialize方法用于初始化校验器，可以获取注解的属性。isValid方法用于实现校验逻辑，返回true表示校验通过，返回false表示校验失败。

使用自定义注解： 现在，就可以在实体类的属性上使用自定义注解了。

public class User {

    @MyCustomAnnotation(message = "用户名必须以custom开头")
    private String username;

    // Getters and setters
}

如何在Spring Boot中启用分组校验？

分组校验允许你根据不同的场景，使用不同的校验规则。例如，在创建用户时需要校验密码，而在更新用户时不需要校验密码。

定义分组接口： 首先，需要定义一些分组接口。这些接口不需要包含任何方法，只需要作为标识即可。
```
public interface CreateUser {
}

public interface UpdateUser {
}
```

在注解中指定分组： 在校验注解中，使用groups属性来指定分组。

import javax.validation.constraints.NotBlank;

public class User {

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

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

    // Getters and setters
}

这里指定username和password属性在CreateUser分组中不能为空。

在Controller中使用： 在Controller中，使用@Validated注解来指定要使用的分组。

import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @PostMapping("/users")
    public String createUser(@Validated(CreateUser.class) @RequestBody User user) {
        // 处理创建用户的逻辑
        return "用户创建成功";
    }

    @PostMapping("/users/{id}")
    public String updateUser(@Validated(UpdateUser.class) @RequestBody User user) {
        // 处理更新用户的逻辑
        return "用户更新成功";
    }
}

注意，这里使用了@Validated注解，而不是@Valid注解。@Validated注解是Spring提供的，用于支持分组校验。

如何处理嵌套对象的校验？

有时候，一个实体类包含另一个实体类作为属性，需要对嵌套对象进行校验。

无限画

千库网旗下AI绘画创作平台

下载

使用@Valid注解： 在包含嵌套对象的属性上，使用@Valid注解。

import javax.validation.Valid;
import javax.validation.constraints.NotBlank;

public class Address {

    @NotBlank(message = "城市不能为空")
    private String city;

    // Getters and setters
}

public class User {

    @NotBlank(message = "用户名不能为空")
    private String username;

    @Valid // 启用嵌套校验
    private Address address;

    // Getters and setters
}

这里在User类的address属性上使用了@Valid注解，表示需要对Address对象进行校验。

在Controller中使用： 在Controller中，和普通对象一样，使用@Valid注解来触发校验。

import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import javax.validation.Valid;

@RestController
public class UserController {

    @PostMapping("/users")
    public String createUser(@Valid @RequestBody User user, BindingResult result) {
        if (result.hasErrors()) {
            // 处理校验失败的情况
            return "校验失败：" + result.getAllErrors().get(0).getDefaultMessage();
        }

        // 处理创建用户的逻辑
        return "用户创建成功";
    }
}

这样，当校验User对象时，会自动校验其address属性对应的Address对象。

校验错误信息国际化

为了支持多语言，需要将校验错误信息进行国际化。

创建ValidationMessages.properties文件： 在src/main/resources目录下，创建一个ValidationMessages.properties文件，用于存放默认的错误提示信息。
```
NotBlank.user.username=用户名不能为空
Size.user.username=用户名长度必须在{min}到{max}之间
```
这里的NotBlank.user.username和Size.user.username分别对应NotBlank和Size注解的错误提示信息。user.username是实体类名和属性名的组合，可以自定义。

在注解中使用{}占位符： 在校验注解中，使用{}占位符来引用ValidationMessages.properties文件中的错误提示信息。

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

public class User {

    @NotBlank(message = "{NotBlank.user.username}")
    @Size(min = 3, max = 20, message = "{Size.user.username}")
    private String username;

    // Getters and setters
}

支持多语言： 创建不同语言的ValidationMessages.properties文件，例如ValidationMessages_zh_CN.properties和ValidationMessages_en_US.properties，用于存放不同语言的错误提示信息。

# ValidationMessages_zh_CN.properties
NotBlank.user.username=用户名不能为空
Size.user.username=用户名长度必须在{min}到{max}之间

# ValidationMessages_en_US.properties
NotBlank.user.username=Username cannot be blank
Size.user.username=Username length must be between {min} and {max}

Spring Boot会自动根据请求的Accept-Language头来选择合适的语言文件。

校验器快速失败模式

默认情况下，Hibernate Validator会校验所有的属性，然后返回所有的错误信息。如果希望在遇到第一个错误时就停止校验，可以使用快速失败模式。

配置ValidatorFactory： 创建一个ValidatorFactory，并配置其为快速失败模式。

import org.hibernate.validator.HibernateValidator;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.validation.beanvalidation.MethodValidationPostProcessor;

import javax.validation.Validation;
import javax.validation.Validator;
import javax.validation.ValidatorFactory;

@Configuration
public class ValidationConfig {

    @Bean
    public MethodValidationPostProcessor methodValidationPostProcessor() {
        return new MethodValidationPostProcessor();
    }

    @Bean
    public Validator validator() {
        ValidatorFactory validatorFactory = Validation.byProvider(HibernateValidator.class)
                .configure()
                .failFast(true) // 开启快速失败模式
                .buildValidatorFactory();
        return validatorFactory.getValidator();
    }
}

这里通过failFast(true)开启了快速失败模式。

使用Validator： 在需要校验的地方，注入Validator对象，并使用其validate方法进行校验。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import javax.validation.ConstraintViolation;
import javax.validation.Validator;
import java.util.Set;

@Service
public class UserService {

    @Autowired
    private Validator validator;

    public void createUser(User user) {
        Set<ConstraintViolation<User>> violations = validator.validate(user);
        if (!violations.isEmpty()) {
            // 处理校验失败的情况
            throw new IllegalArgumentException(violations.iterator().next().getMessage()); // 只返回第一个错误信息
        }

        // 处理创建用户的逻辑
    }
}

这样，当校验User对象时，遇到第一个错误就会停止校验，并抛出异常。

常见错误与解决方案

javax.validation.ValidationException: HV000183: Unable to load 'javax.el.ExpressionFactory'. Check that you have the EL dependencies on the classpath

这个错误通常是由于缺少EL（Expression Language）依赖导致的。需要在pom.xml文件中添加EL依赖：
```
<dependency>
    <groupId>org.glassfish</groupId>
    <artifactId>javax.el</artifactId>
    <version>3.0.1-b09</version>
</dependency>
```
校验注解不生效
- 确认已经添加了spring-boot-starter-validation依赖。
- 确认已经在Controller中使用了@Valid或@Validated注解。
- 确认实体类的属性上使用了正确的校验注解。
- 如果使用了自定义校验注解，确认校验器类实现了ConstraintValidator接口，并且isValid方法返回了正确的校验结果。

自定义校验注解无法获取Spring Bean

如果需要在自定义校验器中使用Spring Bean，可以使用@Autowired注解来注入。但是，需要将校验器类注册为Spring Bean。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;

@Component // 注册为Spring Bean
public class MyCustomValidator implements ConstraintValidator<MyCustomAnnotation, String> {

    @Autowired
    private MyService myService;

    @Override
    public void initialize(MyCustomAnnotation constraintAnnotation) {
        // 初始化方法，可以获取注解的属性
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        // 实现校验逻辑
        if (value == null) {
            return true; // 允许为空
        }
        return myService.isValid(value); // 使用Spring Bean进行校验
    }
}

这样，就可以在校验器中使用MyService Spring Bean了。

希望这些内容能够帮助你更好地理解和使用Spring Boot整合Hibernate验证器。

Java里的线程工厂ThreadFactory怎么自定义_命名与属性批量设置

如何实现Java的类代理加密与解密运行_自定义ClassLoader安全实战

如何解决Java中的线程池任务拒绝导致的业务中断_自定义拒绝处理器

Spring Boot 集成 MapStruct 失败的完整解决方案

Java注解(Annotation)的原理是什么_自定义注解与元注解应用