Spring Boot 3.x中@Bean+@ConfigurationProperties集合验证失效咨询

核心结论 #

• 没有官方规则禁止在@Bean工厂方法中对java.util.List等内置集合类型使用@ConfigurationProperties搭配@Validated/@Valid。
• 验证失效是Spring Boot 3.x的设计变更，而非bug。

原因分析 #

Spring Boot 3.x对配置属性验证逻辑做了两处关键调整：

1. ConfigurationPropertiesJsr303Validator新增了根Bean类型检查，仅针对根Bean执行验证触发逻辑；
2. 适配Jakarta Validation的Hibernate Validator 8.x中，ValidatorImpl仅在根Bean本身带有约束注解时才会启动验证流程。由于java.util.List是JDK内置类，无法添加约束注解，因此无法触发集合内部元素的验证；而自定义包装类（如ValidList<T>）可以通过字段上的@Valid注解触发嵌套验证，所以能正常生效。

可行解决方案 #

方案1：自定义包装类+中间Bean适配（兼容原有注入签名） #

先通过带验证的包装类完成属性绑定与验证，再通过额外的@Bean方法转换为原有集合类型，不影响现有代码的注入逻辑：

// 自定义验证包装类
@Data
public static class ValidList<T> {
    private List<@Valid T> data;
}

// 步骤1：绑定属性并触发验证
@Bean
@ConfigurationProperties("listof.cars")
@Validated
public ValidList<Product> validCars() {
    return new ValidList<>();
}

// 步骤2：适配原有集合类型的注入签名
@Bean
public List<Product> carsAsList(ValidList<Product> validCars) {
    return validCars.getData();
}

方案2：改用配置类绑定（推荐） #

将集合属性封装到专用配置类中，通过@ConfigurationPropertiesScan扫描绑定，这种方式在Spring Boot 3.x中的验证逻辑更稳定：

@ConfigurationProperties(prefix = "list.cars")
@Validated
public class CarProperties {
    @NotEmpty
    private List<@Valid Product> items;

    // 生成getter/setter
}

// 主启动类添加扫描注解
@SpringBootApplication
@ConfigurationPropertiesScan
public class ListValidationApp {
    // 直接注入CarProperties使用
}

补充说明 #

Spring Boot 2.7.x中该场景能生效，是因为当时的验证逻辑会直接遍历集合元素触发验证；而3.x的调整是为了统一根Bean的验证触发规则，避免无约束的根Bean（如内置集合）触发不必要的验证流程。

内容的提问来源于stack exchange，提问作者jim stafford