SpringBoot多数据源配置实战指南

一、先判断：你的项目真的需要多数据源吗

在动手写任何配置之前，有必要先厘清一个前提性问题：多数据源并非普适方案，而是一种带有明确代价的架构选择。引入多数据源意味着事务边界变得复杂、连接池资源成倍增加、Mapper扫描路径需要精细划分，任何一处疏忽都可能导致运行时绑定错误或事务失效。因此在技术选型阶段，应当先用业务事实来验证必要性。

以下三类场景通常构成合理的引入理由：

其一，业务上需要跨库关联查询。 当不同业务域的数据物理隔离在不同数据库中，且没有中间件承担数据同步或联邦查询职责时，应用层直连多个数据源是较为直接的解决方式。此时需要注意，跨库关联查询无法依赖数据库层面的JOIN，往往需要在应用层做内存拼接或分步查询，性能与一致性都需要额外评估。

其二，老系统迁移期间的雙写校验。 系统从旧库向新库迁移时，常需要在一段时间内同时读写新旧两套库，通过比对结果验证迁移正确性。这种场景下多数据源是过渡期的必要手段，但应当明确其临时属性，迁移完成后及时收敛。

其三，轻量级读写分离。 当团队没有条件引入专门的读写分离中间件时，可以通过配置主从两个数据源，配合AOP或注解在方法层面切换数据源来实现读写分离。这种方案实现成本低，但对事务传播、主从延迟等问题需要有清醒认识。

反过来，如果项目只是单库业务，仅仅因为”听说多数据源很高级”就强行引入，结果往往是复杂度陡增而收益为零。事务管理器需要区分、连接池需要叠加、配置类需要拆分，任何一个环节的疏漏都会在后期排查中耗费大量时间。因此第一条原则是：能用单数据源解决的需求，绝不引入多数据源。

二、整体配置流程梳理

多数据源的配置逻辑可以概括为一条清晰的链路：引入必要依赖 → 在配置文件中声明多套数据源参数 → 编写自定义数据源配置类 → 为每个数据源构建独立的SqlSessionFactory → 通过Mapper扫描路径将不同包下的Mapper绑定到对应数据源。

这条链路的核心思想是”隔离”：每个数据源拥有自己的连接池、自己的SqlSessionFactory、自己的Mapper扫描范围，彼此不共享、不干扰。理解这一点，后续每一步配置都有了明确的归属。

三、依赖准备：把基础包导对

配置失败的一大半原因，往往不是逻辑写错，而是依赖缺失或版本冲突。多数据源配置至少需要以下几类依赖：SpringBoot Web核心、MyBatis启动器、数据库驱动、以及可选的连接池实现。

以下是一份精简的依赖清单，基于SpringBoot 2.7.x版本验证可用，更高版本仅需调整版本号即可：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.14</version>
    <relativePath/>
</parent>
<dependencies>
    <!-- Web核心 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- MyBatis启动器 -->
    <dependency>
        <groupId>org.mybatis.spring.boot</groupId>
        <artifactId>mybatis-spring-boot-starter</artifactId>
        <version>2.2.2</version>
    </dependency>
    <!-- 数据库驱动 -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <scope>runtime</scope>
    </dependency>
    <!-- 连接池，可选，默认连接池亦可 -->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>druid-spring-boot-starter</artifactId>
        <version>1.2.16</version>
    </dependency>
</dependencies>

需要强调的是，数据库驱动与连接池属于可替换组件，选择哪一种取决于团队既有技术栈与运维习惯，本文不针对具体产品做推荐。关键点在于：驱动版本必须与数据库服务端版本兼容，连接池配置需要与数据源数量匹配，避免连接数超限。

四、配置文件：为每个数据源声明独立参数

在应用配置文件中，需要为每个数据源分别声明连接参数。为避免与SpringBoot默认单数据源自动配置冲突，通常将自定义数据源参数放在独立的命名空间下，并通过@ConfigurationProperties绑定到对应的数据源Bean上。

spring:
  datasource:
    primary:
      driver-class-name: com.mysql.cj.jdbc.Driver
      jdbc-url: jdbc:mysql://host-a:3306/db_primary?useUnicode=true&characterEncoding=utf8
      username: user_a
      password: pass_a
      maximum-pool-size: 10
    secondary:
      driver-class-name: com.mysql.cj.jdbc.Driver
      jdbc-url: jdbc:mysql://host-b:3306/db_secondary?useUnicode=true&characterEncoding=utf8
      username: user_b
      password: pass_b
      maximum-pool-size: 5

这里有一个容易踩的细节：使用连接池时，URL属性名通常为jdbc-url而非url，若沿用默认自动配置的写法可能导致绑定失败。此外，每个数据源的连接池上限应当根据实际并发量之和来规划，避免多数据源叠加后超过数据库端的最大连接数限制。

五、自定义数据源配置类：隔离是关键

配置类的职责是为每个数据源创建独立的DataSource、SqlSessionFactory与SqlSessionTemplate，并指定各自的Mapper扫描路径。以下以两个数据源为例给出结构示意：

@Configuration
@MapperScan(basePackages = "com.example.mapper.primary",
            sqlSessionFactoryRef = "primarySqlSessionFactory")
public class PrimaryDataSourceConfig {
    @Bean(name = "primaryDataSource")
    @ConfigurationProperties(prefix = "spring.datasource.primary")
    public DataSource primaryDataSource() {
        return DataSourceBuilder.create().build();
    }
    @Bean(name = "primarySqlSessionFactory")
    public SqlSessionFactory primarySqlSessionFactory(
            @Qualifier("primaryDataSource") DataSource dataSource) throws Exception {
        SqlSessionFactoryBean factoryBean = new SqlSessionFactoryBean();
        factoryBean.setDataSource(dataSource);
        return factoryBean.getObject();
    }
    @Bean(name = "primarySqlSessionTemplate")
    public SqlSessionTemplate primarySqlSessionTemplate(
            @Qualifier("primarySqlSessionFactory") SqlSessionFactory factory) {
        return new SqlSessionTemplate(factory);
    }
}

第二个数据源的配置类结构完全对称，只需替换包路径、Bean名称与配置前缀。这里的关键点有三处：

第一，@MapperScan必须显式指定sqlSessionFactoryRef。 否则多个SqlSessionFactory共存时，MyBatis无法确定使用哪一个，启动阶段即会报错。

第二，Bean名称必须唯一且可被@Qualifier精确引用。 方法名即Bean名，注入时通过限定符消除歧义，这是多数据源能够共存的基础。

第三，主数据源需要标注@Primary。 当存在多个同类型Bean时，未指定限定符的注入点会默认选择主Bean，可避免大量不必要的显式限定符声明。但需注意，@Primary只是兜底策略，不应成为掩盖注入歧义的借口。

六、事务管理：多数据源下必须明确的边界

多数据源场景下，事务管理器不再能依赖自动配置。每个数据源应当配置独立的DataSourceTransactionManager，并在@Transactional注解中通过transactionManager属性显式指定。需要清醒认识的是：跨数据源的本地事务无法保证原子性，若业务涉及跨库写入的一致性，必须引入分布式事务方案或通过业务补偿来保证最终一致，不能想当然地认为一个注解就能覆盖两个库。

七、常见问题与排查思路

实际落地过程中，以下几类问题出现频率较高：

• 启动报”required a single bean, but N were found”：典型的多Bean注入歧义，检查注入点是否缺少@Qualifier，或主数据源是否遗漏@Primary。
• Mapper绑定到错误的数据源：检查@MapperScan的包路径是否重叠，扫描范围必须互斥，不能出现一个Mapper被两个配置类同时扫描的情况。
• 连接池耗尽：多数据源意味着连接数叠加，需按总量规划各池上限，并监控实际使用率。
• 事务不生效：确认@Transactional指定的管理器与目标数据源一致，同时注意同类内部方法调用不会触发代理。

八、小结

多数据源配置的本质是”隔离”二字：数据源隔离、会话工厂隔离、扫描路径隔离、事务管理器隔离。把这四层隔离理清楚，配置过程就是按部就班的机械操作。但更重要的是配置之前的那一步判断——确认业务确实需要，确认复杂度可控，确认团队有能力维护。技术选型的成熟度，往往体现在知道什么时候不该用它。