1. 引言
Spring Boot 2.1 的升级让不少开发者踩了坑——原本正常运行的项目突然抛出 BeanDefinitionOverrideException。这个异常让人一头雾水：Spring 不是本来就支持 Bean 覆盖吗？怎么现在反而报错了？
本文将深入剖析这个问题的根源，并提供几种简单粗暴又安全的解决方案，帮你快速定位和修复。
2. Maven 依赖
为了演示，我们使用标准的 Spring Boot Starter 依赖：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
<version>3.1.5</version>
</dependency>
✅ 确保你的项目已引入此依赖，后续示例基于 Spring Boot 3.x 环境。
3. Bean 覆盖机制回顾
在 Spring 的 ApplicationContext 中，每个 Bean 都通过名称唯一标识。
因此，当两个 Bean 使用了相同的名称时，后定义的会覆盖先定义的——这就是默认的 Bean 覆盖行为。
但从 Spring 5.1 开始，框架引入了 BeanDefinitionOverrideException，允许开发者主动禁止这种覆盖行为，避免意外发生。
⚠️ 默认情况下，Spring 仍允许覆盖，但 Spring Boot 2.1 起默认关闭了该功能，这就是问题的根源。
4. Spring Boot 2.1 的配置变更
Spring Boot 2.1 出于防御性设计，默认禁用了 Bean 覆盖（bean overriding）。目的是提前暴露重复的 Bean 名称，防止开发者无意中覆盖关键组件。
这意味着：如果你的项目依赖了 Bean 覆盖逻辑（比如通过配置类覆盖第三方库的默认 Bean），升级到 2.1+ 后大概率会抛出 BeanDefinitionOverrideException。
接下来我们通过一个典型场景复现这个问题。
5. 定位冲突的 Bean
我们创建两个配置类，各自定义一个名为 testBean 的 Bean：
@Configuration
public class TestConfiguration1 {
class TestBean1 {
private String name;
// standard getters and setters
}
@Bean
public TestBean1 testBean(){
return new TestBean1();
}
}
@Configuration
public class TestConfiguration2 {
class TestBean2 {
private String name;
// standard getters and setters
}
@Bean
public TestBean2 testBean(){
return new TestBean2();
}
}
然后编写测试类加载这两个配置：
@RunWith(SpringRunner.class)
@SpringBootTest(classes = {TestConfiguration1.class, TestConfiguration2.class})
public class SpringBootBeanDefinitionOverrideExceptionIntegrationTest {
@Test
public void whenBeanOverridingAllowed_thenTestBean2OverridesTestBean1() {
Object testBean = applicationContext.getBean("testBean");
assertThat(testBean.getClass()).isEqualTo(TestConfiguration2.TestBean2.class);
}
}
运行测试，直接抛出异常：
Invalid bean definition with name 'testBean' defined in ...
... com.example.config.TestConfiguration2 ...
Cannot register bean definition [ ... defined in ...
... com.example.config.TestConfiguration2] for bean 'testBean' ...
There is already [ ... defined in ...
... com.example.config.TestConfiguration1] bound.
关键信息提取：
- ❌ 冲突的 Bean 名称：
testBean - ❌ 涉及的配置类：
TestConfiguration1和TestConfiguration2
这说明两个不同类型的 Bean 使用了相同名称，Spring Boot 拒绝自动覆盖。
6. 解决方案
根据实际场景，有多种方式解决此问题。优先推荐从设计上避免名称冲突，其次才是开启覆盖。
6.1. 修改方法名（最简单）
Spring 默认以 @Bean 注解的方法名作为 Bean 名称。因此，最简单的做法是改方法名：
@Bean
public TestBean1 testBean1() {
return new TestBean1();
}
@Bean
public TestBean2 testBean2() {
return new TestBean2();
}
✅ 无需额外配置，清晰明了，推荐优先使用。
6.2. 显式指定 @Bean 名称
通过 @Bean 注解的 name 属性显式命名：
@Bean("testBean1")
public TestBean1 testBean() {
return new TestBean1();
}
@Bean("testBean2")
public TestBean2 testBean() {
return new TestBean2();
}
✅ 灵活控制名称，适合需要统一命名规范的场景。
⚠️ 注意：第二个示例中虽然方法名仍是 testBean，但实际注册的 Bean 名是 testBean2。
6.3. 使用 Stereotype 注解（如 @Component）
如果你使用的是组件扫描（@ComponentScan），可以直接在类上使用 @Component 并指定名称：
@Component("testBean1")
class TestBean1 {
private String name;
// getters and setters
}
@Component("testBean2")
class TestBean2 {
private String name;
// getters and setters
}
✅ 适用于非配置类场景，比如 Service、Repository 等。
6.4. 第三方库冲突？开启覆盖（慎用）
有时候冲突来自第三方库（比如你引入的 starter 定义了一个 dataSource，你也想自定义一个同名 Bean）。
此时如果无法修改第三方代码，可以临时开启 Bean 覆盖：
在 application.properties 中添加：
spring.main.allow-bean-definition-overriding=true
或者在 application.yml：
spring:
main:
allow-bean-definition-overriding: true
⚠️ 警告：开启后，无法保证哪个 Bean 会被最终加载，因为加载顺序受依赖关系和类路径扫描影响，具有不确定性。
✅ 仅建议在以下情况使用：
- 快速验证问题
- 确认覆盖行为可控
- 临时过渡方案
❌ 生产环境不建议长期开启，容易埋下隐患。
7. 总结
| 方案 | 推荐度 | 适用场景 |
|---|---|---|
| 修改方法名 | ✅✅✅ | 自定义配置类，最安全 |
| @Bean 指定名称 | ✅✅✅ | 需要统一命名 |
| @Component 指定名称 | ✅✅ | 组件扫描场景 |
| 开启 allow-bean-definition-overriding | ⚠️ | 第三方库冲突，临时方案 |
📌 核心要点：
- Spring Boot 2.1+ 默认禁止 Bean 覆盖，防止意外。
BeanDefinitionOverrideException是保护机制，不是 Bug。- 优先通过命名规避冲突，而非强行开启覆盖。
- 生产环境务必明确每个 Bean 的来源和优先级。
完整示例代码已托管至 GitHub：https://github.com/example/spring-boot-bean-override-demo