首页 > 软件编程 > java > SpringBoot配置校验

SpringBoot3.4配置校验新特性的用法详解

2025-04-29 14:49:15 作者：星辰聊技术

Spring Boot 3.4 对配置校验支持进行了全面升级,这篇文章为大家详细介绍了一下它们的具体使用,文中的示例代码讲解详细,感兴趣的小伙伴可以参考一下

配置属性验证增强亮点

Spring Boot 3.4 对配置校验支持进行了全面升级，核心亮点包括：

支持 jakarta.validation 全套标准注解（如 @NotNull、@Email、@Pattern 等）
嵌套对象、集合元素 的深度校验支持
启动阶段校验失败，IDE友好提示，快速定位问题
自动生成更完善的开发时元信息（metadata）

可以说，从易用性到严谨性，都有了质的飞跃！

基本用法示例

定义配置类

以用户配置为例：

package com.icoderoad.demo.config;


import jakarta.validation.Valid;
import jakarta.validation.constraints.*;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;


import java.util.List;


@Validated
@ConfigurationProperties(prefix = "app.user")
public class UserProperties {


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


    @Email(message = "邮箱格式不正确")
    private String email;


    @Min(value = 18, message = "年龄不能小于18岁")
    private Integer age;


    @Valid
    private Address address;


    @Size(min = 1, message = "至少需要一个角色")
    private List<@NotBlank(message = "角色名称不能为空") String> roles;


    // Address是嵌套对象，需要加@Valid
    public static class Address {
        @NotBlank(message = "城市不能为空")
        private String city;


        @Pattern(regexp = "\d{6}", message = "邮编必须是6位数字")
        private String zipCode;


        // getter/setter
        public String getCity() {
            return city;
        }
        public void setCity(String city) {
            this.city = city;
        }
        public String getZipCode() {
            return zipCode;
        }
        public void setZipCode(String zipCode) {
            this.zipCode = zipCode;
        }
    }


    // getter/setter
    public String getUsername() {
        return username;
    }
    public void setUsername(String username) {
        this.username = username;
    }
    public String getEmail() {
        return email;
    }
    public void setEmail(String email) {
        this.email = email;
    }
    public Integer getAge() {
        return age;
    }
    public void setAge(Integer age) {
        this.age = age;
    }
    public Address getAddress() {
        return address;
    }
    public void setAddress(Address address) {
        this.address = address;
    }
    public List<String> getRoles() {
        return roles;
    }
    public void setRoles(List<String> roles) {
        this.roles = roles;
    }
}

配置 application.yml

app:
  user:
    username: "张三"
    email: "zhangsan@example.com"
    age: 25
    address:
      city: "上海"
      zipCode: "200000"
    roles:
      - "admin"
      - "user"

注入使用

在你的服务中注入：

package com.icoderoad.demo.service;


import com.example.demo.config.UserProperties;
import org.springframework.stereotype.Service;


@Service
public class UserService {


    private final UserProperties userProperties;


    public UserService(UserProperties userProperties) {
        this.userProperties = userProperties;
    }


    public void printUserInfo() {
        System.out.println("用户名：" + userProperties.getUsername());
        System.out.println("邮箱：" + userProperties.getEmail());
    }
}

嵌套对象与集合元素深度校验

注意，在嵌套对象上必须标注 @Valid，才能对子属性继续校验。集合元素（如 List<String>）同样支持元素级校验注解！

这让配置类的约束更加细粒度、安全。

启动阶段即校验失败

如果配置不符合要求，比如漏填 username、邮箱格式错误、年龄不足18岁、角色列表为空等，Spring Boot 启动时就会直接报错！

示例错误日志：

***************************
APPLICATION FAILED TO START
***************************

Description:

Binding to target [Bindable@xxx type = com.icoderoad.demo.config.UserProperties] failed:

Property: app.user.username
Value:
Reason: 用户名不能为空

Property: app.user.email
Value: not-an-email
Reason: 邮箱格式不正确

非常直观，能第一时间发现配置问题，避免服务上线后隐患！

开发时元信息增强

配合 Spring Boot 的 spring-boot-configuration-processor 插件，还能自动生成提示补全信息（IDE 中 .yml 配置智能提示）！

pom.xml 配置：

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<optional>true</optional>
</dependency>

编译后，会生成 META-INF/spring-configuration-metadata.json，供 IDE 智能补全参考。

注意事项

@ConfigurationProperties
必须配合 @Validated
嵌套对象字段要加 @Valid
集合元素校验，需要在泛型上加注解
使用 Jakarta Validation 标准注解（Spring Boot 3.x 默认使用 Jakarta）

扩展：错误处理更友好（自定义异常消息格式）

默认启动校验失败时，Spring Boot 抛出 BindValidationException，信息虽然完整但略显杂乱。为了让错误提示更专业友好，我们可以自定义异常处理。

定义友好的异常类

package com.icoderoad.demo.exception;


/**
 * 自定义配置校验异常
 */
public class ConfigValidationException extends RuntimeException {


    public ConfigValidationException(String message) {
        super(message);
    }
}

编写异常处理器

通过 BeanFactoryPostProcessor 统一拦截配置阶段的校验错误：

package com.icoderoad.demo.exception;


import org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanFactoryPostProcessor;
import org.springframework.boot.context.properties.bind.BindValidationException;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.validation.ObjectError;


import java.util.stream.Collectors;


@Configuration
public class ConfigValidationExceptionHandler {


    @Bean
    public static BeanFactoryPostProcessor configurationPropertiesValidator() {
        return beanFactory -> {
            try {
                // 手动触发bean初始化
            } catch (BeansException ex) {
                Throwable cause = ex.getCause();
                if (cause instanceof BindValidationException bindValidationException) {
                    String errorMessages = bindValidationException.getValidationErrors()
                            .getAllErrors()
                            .stream()
                            .map(ObjectError::getDefaultMessage)
                            .collect(Collectors.joining("; "));
                    throw new ConfigValidationException("配置属性校验失败：" + errorMessages);
                }
                throw ex;
            }
        };
    }
}

逻辑解释：

捕获 BindValidationException
提取所有校验失败信息
使用 ; 拼接成简洁可读的文本
抛出我们的 ConfigValidationException

示例效果

比如你的配置错误如下：

app:
  user:
    username: ""
    email: "wrong"
    age: 15
    address:
      city: ""
      zipCode: "12abc"
    roles:
      - ""

启动时抛出的错误变成：

配置属性校验失败：用户名不能为空; 邮箱格式不正确; 年龄不能小于18岁; 城市不能为空; 邮编必须是6位数字; 角色名称不能为空

信息集中、简洁直观
一次性列出所有问题，快速修复
适合前后端、测试同事快速理解

总结

Spring Boot 3.4 配置属性验证：

验证能力更强大覆盖深度校验、集合元素校验
开发体验更极致启动即校验，IDE智能提示
错误处理更优雅可自定义异常格式
提升整体代码质量避免配置隐患上线

在实际项目中，推荐配合自定义异常机制，打造更加专业可靠的配置校验体系！

到此这篇关于SpringBoot3.4配置校验新特性的用法详解的文章就介绍到这了,更多相关SpringBoot配置校验内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！