Spring Boot项目Validator注入多OptionalValidatorFactoryBean实例异常排查

对应问题场景：Spring Boot 2.3.4.RELEASE多模块项目启动时，因注入javax.validator.Validator抛出NoUniqueBeanDefinitionException，上下文存在多个命名为OptionalValidatorFactoryBean#0至OptionalValidatorFactoryBean#4的同类型Bean，无法通过修改第三方类的@Qualifier逻辑绕开冲突。

核心排查路径 #

• 定位Bean定义的真实来源，跳过运行时实例的表层干扰
  不要仅打印上下文内的Bean实例列表，直接在BeanFactoryPostProcessor实现类中获取ConfigurableListableBeanFactory，遍历所有Bean名称，匹配类型为OptionalValidatorFactoryBean的条目，逐行打印每个Bean对应的resourceDescription、source属性。这两个属性会直接标记该Bean定义的注册来源（具体哪个配置类、哪个jar包内的类），不存在模糊判断空间。
• 排查自动配置重复加载的典型触发条件
  Spring Boot 2.3.4版本默认的ValidationAutoConfiguration仅会注册1个全局Validator Bean，出现多实例的核心原因是多模块链路下的重复加载：
  • 逐模块检查所有META-INF/spring.factories文件，确认是否有模块手动将ValidationAutoConfiguration加入自动配置列表，导致同一个配置类被多次加载触发Bean注册。
  • 排查所有模块的组件扫描配置，确认是否存在跨模块宽范围扫描（比如将扫描根路径设为全局包名），导致同一个配置类被多次扫描识别，重复注册内部声明的Bean。
  • 逐模块检查依赖引入情况，确认是否有多个子模块单独引入了Validation相关starter，导致自动配置类被多个类加载链路重复识别。
• 排查冗余的手动Bean注册逻辑
  多模块项目中常出现不同模块各自声明Validator Bean的情况：
  • 全局搜索所有代码中，返回值类型为Validator、ValidatorFactory、LocalValidatorFactoryBean、OptionalValidatorFactoryBean的@Bean方法，逐行核对所在类、所在模块。
  • 特别注意：若某个@Bean方法的返回值声明为javax.validation.Validator接口，但实际返回实例是OptionalValidatorFactoryBean，这类Bean也会被纳入同类型候选列表，属于核心冲突来源。
• 排查第三方依赖的内部注册逻辑
  结合之前打印的Bean定义来源属性，定位指向第三方jar包的注册条目，直接跳转对应类的代码确认是否存在重复注册逻辑。注意：hibernate-validator 6.1.5.FINAL本身仅提供校验实现能力，不会主动注册Spring容器的Bean，所有Spring层面的Validator Bean注册逻辑必然来自Spring生态的配置类，不会来自Hibernate Validator本身。

快速恢复方案（非根因修复，仅用于临时止血） #

如果需要快速恢复服务，可在主启动类中排除默认的Validation自动配置，手动注册全局唯一的Validator Bean覆盖所有模块的校验逻辑：

@SpringBootApplication(exclude = ValidationAutoConfiguration.class)
public class Application {
    @Bean
    public Validator globalValidator() {
        LocalValidatorFactoryBean factoryBean = new LocalValidatorFactoryBean();
        // 可根据需要追加国际化、消息源绑定等配置
        return factoryBean;
    }
}

该方案可快速消除多实例冲突，但仍建议通过上述排查路径定位重复注册的根源，避免后续出现校验规则不一致的隐性问题。

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