在 Spring Boot 应用里，当我们引入多个同类型的 Bean，例如配置了主库和从库两个 DataSource，容器在自动装配时会抛出 NoUniqueBeanDefinitionException。很多初学者以为存在一个叫 @EnablePrimary 的开关注解，实际上 Spring 并没有提供该名称的启用注解，真正起作用的是 @Primary 标记。它直接标注在 Bean 定义方法或类上，告诉 Spring 在存在多个候选 Bean 时优先选择被标记的那个。下面通过具体配置和代码，说明如何用它化解多数据源冲突。
@Primary 注解的底层注入优先级原理
Spring 在启动阶段会扫描所有 @Configuration 类，将 @Bean 方法返回的实例注册到 BeanFactory 中。当某个字段或构造参数使用 @Autowired 且未指定名称时，DefaultListableBeanFactory 会调用 resolveCandidate 方法收集所有类型匹配的 Bean。如果找到多个，就会检查其中是否有标记为 @Primary 的实例。@Primary 的元数据在 BeanDefinition 中通过 isPrimary 属性保存，优先级判定逻辑在 determinePrimaryCandidate 方法中完成，它直接返回 primary 为 true 的那个 Bean，从而绕开歧义。
需要注意的是，@Primary 仅在同一类型的多个 Bean 之间生效，它不能跨类型提升优先级。若项目中同时存在 DataSource 和 AbstractRoutingDataSource，两者类型不同，不会触发候选冲突。此外，@Primary 的生效范围是整个 ApplicationContext，如果在主容器和子容器中都有同类型 Bean，子容器会优先用自己的，父容器的 @Primary 不会向下穿透。理解这一点，才能避免在模块化项目中误以为标记一次就全局通用。
从生命周期看，@Primary 在 Bean 定义阶段就已确定，运行期无法动态更改。如果需要根据请求切换数据源，应结合 AbstractRoutingDataSource 而非依赖 @Primary。但在固定主从分工、测试替身等静态场景中，@Primary 是最轻量的方案，不需要写任何条件判断代码，也不会引入额外代理层，性能开销可以忽略。
多数据源场景下 @Primary 的配置实战
假设项目需要连接订单库和用户库两个 MySQL 实例。我们编写两个配置类，分别声明 DataSource，并在主库配置上标注 @Primary。这样业务层默认的 @Autowired DataSource 就会注入主库，而从库通过 @Qualifier 显式引用。下面给出主库配置示例，其中使用了 HikariCP 连接池，并设置了基本连接参数。
@Configuration
public class PrimaryDataSourceConfig {
@Primary
@Bean(name = "primaryDataSource")
@ConfigurationProperties(prefix = "spring.datasource.primary")
public DataSource primaryDataSource() {
// 使用 Spring Boot 自动绑定的 Hikari 配置
return DataSourceBuilder.create().type(HikariDataSource.class).build();
}
}
从库配置则不添加 @Primary，但必须指定不同的 Bean 名称，否则会被主库覆盖。在 Service 中注入时，未加 @Qualifier 的字段自动拿主库，需要查从库的方法通过 @Qualifier("slaveDataSource") 获取。这种写法让大部分读写逻辑无需关心数据源路由，只有少数报表查询显式声明，降低了代码侵入性。
如果误将两个 DataSource 都标了 @Primary，Spring 会在刷新上下文时抛出 NoUniqueBeanDefinitionException，因为此时存在多个 primary 候选。因此团队应约定仅一个主库配置类使用 @Primary，并在代码评审中检查。另外，当使用 @SpringBootTest 且需要 Mock 主库时，可在测试配置里用 @Primary 标注 Mock Bean，从而覆盖正式配置，这是单元测试中常见的替身手法。
与 @Qualifier、排除自动配置等方案的对比
除了 @Primary，开发者常使用 @Qualifier 按名称注入。@Qualifier 要求每个注入点都写明文名称，虽然精准但冗余度高，适合 Bean 数量多且需频繁指定不同实现的场景。@Primary 则把默认选择集中到定义侧，调用侧保持干净。两者可以混用：定义侧标 @Primary 作为兜底，特殊地方用 @Qualifier 覆盖，Spring 会优先采用 @Qualifier 指定的名称。
另一种思路是排除 Spring Boot 的 DataSourceAutoConfiguration，自己完全掌控所有 Bean 创建，这样不会有多余的自动 Bean 干扰。缺点是失去了 spring.datasource 前缀的自动绑定便利，需要手动读取配置。对于简单多数据源，@Primary 加 @ConfigurationProperties 已足够，不必关停自动配置。下面的表格列出三种方案差异：
| 方案 | 配置位置 | 调用侧负担 | 适用场景 |
|---|---|---|---|
| @Primary | Bean 定义处 | 低 | 固定主从、测试替身 |
| @Qualifier | 注入点 | 高 | 多实现需精确指定 |
| 排除自动配置 | 入口注解 | 中 | 完全自定义数据源结构 |
从维护成本看，@Primary 的语义清晰，新成员容易理解哪个是默认数据源。若项目后续引入动态数据源路由，可保留 @Primary 标注的路由数据源作为默认，其他具体库通过 Key 获取。总之，所谓 Spring Boot EnablePrimary 实质就是合理使用 @Primary，它虽无独立启用注解，却能有效化解 Bean 冲突，是整合多数据源时首先应考虑的基础手段。
Spring_BootEnablePrimary多数据源修改时间：2026-08-16 14:14:13