1. 项目概述为什么需要配置多个数据源在真实的业务开发中一个Spring Boot应用只连接一个数据库的场景往往只存在于教科书或者最简单的Demo里。随着业务复杂度的提升我们不可避免地会遇到需要同时操作多个数据库的情况。比如你的用户数据可能存放在一个高性能的MySQL集群里而订单和交易流水这类强事务性数据则存放在另一个独立的MySQL实例中同时为了做实时分析或缓存你可能还需要连接Redis或者Elasticsearch。更常见的场景是在微服务架构下虽然提倡每个服务有自己的数据库但有时为了历史包袱、数据聚合分析或是特定的业务需求一个服务需要“跨库”查询这时候多数据源配置就成了必须掌握的技能。很多人一听到“多数据源”就觉得是高级特性心生畏惧。其实它的核心思想很简单不就是创建多个DataSource对象然后告诉Spring在什么时候用哪一个嘛。但真动手配起来坑却不少。比如事务管理怎么搞MyBatis的Mapper怎么绑定到特定的数据源多个数据源下的连接池参数如何优化这些问题如果不搞清楚轻则性能低下重则数据错乱。今天我就结合自己趟过的坑把Spring Boot配置多数据源的几种主流方案掰开揉碎了讲清楚从最基础的手动配置到基于注解的优雅方案再到动态数据源的进阶玩法并附上详细的避坑指南。2. 核心方案选型与设计思路拆解面对多数据源需求我们通常有三种主流的设计思路每种都有其适用的场景和优缺点。选择哪种取决于你的业务复杂度和对代码侵入性的容忍度。2.1 方案一基于配置类的显式定义这是最基础、最直观的方式。其核心思想是我们完全绕开Spring Boot的自动配置spring-boot-starter-jdbc或spring-boot-starter-data-jpa提供的默认DataSource自己手动在Java配置类里定义两个或多个DataSource、SqlSessionFactory、TransactionManager等Bean。为什么选择它绝对控制权每一个Bean的创建、每一个属性的设置都完全掌握在自己手中。你可以为不同数据源定制截然不同的连接池参数比如主库连接池大一些用于报表的只读库连接池小一些。清晰隔离每个数据源相关的Bean数据源、事务管理器、MyBatis工厂被组织在独立的配置类或方法中物理和逻辑上都做到了隔离便于理解和维护。学习成本低非常适合作为多数据源的入门学习方案你能清晰地看到整个装配链条。它的缺点也很明显代码冗余每个数据源都要重复写一套类似的Bean定义代码如果数据源多配置文件会显得臃肿。Mapper绑定麻烦你需要通过MapperScan注解显式地指定每个SqlSessionFactory扫描的Mapper接口包路径必须保证Mapper接口按数据源分包存放这对已有项目结构可能造成较大冲击。2.2 方案二基于AbstractRoutingDataSource的动态数据源这是更高级、更灵活的方案常用于需要运行时动态切换数据源的场景比如根据租户ID切换数据库多租户SaaS或者根据业务操作类型选择主库或从库。它的工作原理AbstractRoutingDataSource是一个抽象的路由数据源它本身并不管理真实的数据库连接而是作为一个“路由器”存在。它内部维护了一个“目标数据源Map”key是数据源的标识符如masterslavevalue是真实的DataSource对象。同时它依赖一个determineCurrentLookupKey()方法这个方法返回当前线程应该使用哪个数据源的key。我们只需要继承这个类并实现这个方法就能实现动态切换。为什么选择它动态灵活数据源切换可以在运行时根据代码逻辑如AOP切面动态决定无需重启应用。对业务代码透明业务层的Service代码可以不关心具体操作哪个库只需要在操作前通常通过自定义注解AOP设置好数据源key即可。统一入口整个应用在Spring眼中只有一个DataSourceBean即这个路由数据源简化了部分配置。它的挑战在于事务管理复杂动态切换如果和Transactional注解混用极易出错。因为Spring的事务管理器通常在事务开始时就从数据源获取连接并在整个事务中持有它。如果在事务中途切换数据源往往无效可能导致数据错乱。通常需要搭配自定义的事务管理器或更精细的AOP控制。连接池管理路由数据源背后的每个真实数据源都有自己的连接池需要分别配置和监控。2.3 方案三第三方框架如MyBatis-Plus多数据源模块如果你在使用MyBatis-Plus那么恭喜你它提供了开箱即用的多数据源支持dynamic-datasource-spring-boot-starter。这个方案可以看作是方案二的“加强版”和“标准化”实现。为什么选择它极简配置在yaml文件中按格式定义多个数据源几乎零代码即可启用。注解驱动通过DS(“数据源名”)注解可以轻松在Service层或Mapper层方法上指定使用的数据源非常优雅。内置事务处理框架对多数据源下的事务处理有较好的支持虽然复杂事务仍需谨慎降低了自行处理事务传播的难度。功能丰富支持负载均衡、分组、SPI扩展等高级特性。它的局限性框架绑定你被绑定在了MyBatis-Plus生态上。黑盒性出了问题需要深入理解框架内部机制才能排查对于想深刻理解多数据源原理的开发者来说可能一开始会有些迷茫。选择建议对于新手或明确使用MyBatis-Plus的项目强烈推荐方案三。对于想深入理解原理、或有高度定制化需求且不用MyBatis-Plus的场景可以从方案一开始学习再过渡到方案二。下文我们将以最经典的方案一作为主线进行详解因为它最能揭示底层原理。3. 基于配置类的多数据源配置详解我们以一个最常见的场景为例一个应用需要同时操作一个主库master-db 用于核心业务读写和一个从库slave-db 用于复杂查询或报表。我们将使用Spring Boot MyBatis HikariCPSpring Boot默认连接池来实现。3.1 项目结构与依赖准备首先确保你的pom.xml包含了必要的依赖dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-jdbc/artifactId /dependency !-- MyBatis Spring Boot Starter -- dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version你的版本/version /dependency !-- MySQL 驱动 -- dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies项目结构规划如下关键在于按数据源对Mapper接口进行分包src/main/java/com/example/demo/ ├── config │ ├── MasterDataSourceConfig.java │ └── SlaveDataSourceConfig.java ├── mapper │ ├── master // 对应主库操作的Mapper接口 │ │ └── UserMasterMapper.java │ └── slave // 对应从库操作的Mapper接口 │ └── ReportSlaveMapper.java ├── service │ └── SomeService.java └── DemoApplication.java3.2 主数据源Master配置类创建MasterDataSourceConfig.javaConfiguration MapperScan(basePackages com.example.demo.mapper.master, sqlSessionFactoryRef masterSqlSessionFactory) public class MasterDataSourceConfig { /** * 主数据源配置前缀 */ Primary // 重点标记为首选数据源当存在多个同类型Bean时优先注入此Bean Bean(name masterDataSource) ConfigurationProperties(prefix spring.datasource.master) public DataSource masterDataSource() { // Spring Boot会自动使用HikariCP并根据spring.datasource.master下的配置构建DataSource return DataSourceBuilder.create().build(); } /** * 主数据源的事务管理器 */ Primary Bean(name masterTransactionManager) public DataSourceTransactionManager masterTransactionManager( Qualifier(masterDataSource) DataSource dataSource) { return new DataSourceTransactionManager(dataSource); } /** * 主数据源的SqlSessionFactory * 需要指定1.使用的数据源 2.Mapper XML文件的位置 */ Primary Bean(name masterSqlSessionFactory) public SqlSessionFactory masterSqlSessionFactory( Qualifier(masterDataSource) DataSource dataSource) throws Exception { SqlSessionFactoryBean sessionFactoryBean new SqlSessionFactoryBean(); sessionFactoryBean.setDataSource(dataSource); // 设置主库对应的Mapper XML文件路径同样建议按数据源分隔目录 sessionFactoryBean.setMapperLocations( new PathMatchingResourcePatternResolver().getResources( classpath:mapper/master/*.xml)); // 可在此进行其他MyBatis全局配置如驼峰命名转换 org.apache.ibatis.session.Configuration configuration new org.apache.ibatis.session.Configuration(); configuration.setMapUnderscoreToCamelCase(true); sessionFactoryBean.setConfiguration(configuration); return sessionFactoryBean.getObject(); } }关键点解析Primary这个注解至关重要。当Spring容器中存在多个DataSource或TransactionManager类型的Bean时它标记哪个是默认的。通常我们会将写操作更多、更核心的数据源设为首选。如果不加Spring在自动注入时会因无法做出选择而报错。MapperScan这是MyBatis-Spring的注解用于指定该SqlSessionFactory应该扫描哪些包下的Mapper接口。sqlSessionFactoryRef属性明确指向本配置类中定义的masterSqlSessionFactoryBean。这样就建立了master包下的Mapper接口与主数据源的绑定关系。ConfigurationProperties它使得application.yml中spring.datasource.master开头的属性自动注入到DataSourceBuilder创建的DataSource对象中非常方便。事务管理器每个数据源必须有自己独立的事务管理器DataSourceTransactionManager。这是保证事务在正确数据源上执行的关键。3.3 从数据源Slave配置类创建SlaveDataSourceConfig.javaConfiguration MapperScan(basePackages com.example.demo.mapper.slave, sqlSessionFactoryRef slaveSqlSessionFactory) public class SlaveDataSourceConfig { Bean(name slaveDataSource) ConfigurationProperties(prefix spring.datasource.slave) public DataSource slaveDataSource() { return DataSourceBuilder.create().build(); } Bean(name slaveTransactionManager) public DataSourceTransactionManager slaveTransactionManager( Qualifier(slaveDataSource) DataSource dataSource) { return new DataSourceTransactionManager(dataSource); } Bean(name slaveSqlSessionFactory) public SqlSessionFactory slaveSqlSessionFactory( Qualifier(slaveDataSource) DataSource dataSource) throws Exception { SqlSessionFactoryBean sessionFactoryBean new SqlSessionFactoryBean(); sessionFactoryBean.setDataSource(dataSource); sessionFactoryBean.setMapperLocations( new PathMatchingResourcePatternResolver().getResources( classpath:mapper/slave/*.xml)); // 同样可以设置独立的MyBatis配置 org.apache.ibatis.session.Configuration configuration new org.apache.ibatis.session.Configuration(); configuration.setMapUnderscoreToCamelCase(true); sessionFactoryBean.setConfiguration(configuration); return sessionFactoryBean.getObject(); } }这个配置类与主数据源配置类结构完全一致只是去掉了Primary注解并且所有Bean的name、扫描的包路径、配置前缀都换成了slave。3.4 应用配置文件在application.yml中配置两个数据源的连接信息spring: datasource: master: jdbc-url: jdbc:mysql://localhost:3306/master_db?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root password: master_password driver-class-name: com.mysql.cj.jdbc.Driver hikari: pool-name: MasterHikariPool maximum-pool-size: 20 # 主库连接池可以大一些 minimum-idle: 10 connection-timeout: 30000 idle-timeout: 600000 max-lifetime: 1800000 slave: jdbc-url: jdbc:mysql://localhost:3307/slave_db?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root password: slave_password driver-class-name: com.mysql.cj.jdbc.Driver hikari: pool-name: SlaveHikariPool maximum-pool-size: 15 # 从库连接池可以稍小 minimum-idle: 5 connection-timeout: 30000配置心得使用jdbc-url而非url在HikariCP与Spring Boot特定版本组合下使用jdbc-url可以避免一些潜在的配置解析问题。为连接池命名pool-name这在监控和排查问题时非常有用你能在日志或监控面板中清晰区分是哪个库的连接池出了问题。差异化配置根据数据源的角色调整连接池参数。主库承担写压力连接池可以设置得大一些从库主要用于读可以适当调小避免占用过多数据库连接资源。3.5 Mapper与Service层使用在对应的包下创建Mapper接口和XML文件// 文件位置src/main/java/com/example/demo/mapper/master/UserMasterMapper.java package com.example.demo.mapper.master; Mapper // 或由MapperScan扫描注册 public interface UserMasterMapper { int insert(User user); int updateById(User user); }// 文件位置src/main/java/com/example/demo/mapper/slave/ReportSlaveMapper.java package com.example.demo.mapper.slave; Mapper public interface ReportSlaveMapper { ListReportData selectComplexReport(MapString, Object params); }在Service中使用时直接注入对应的Mapper即可。事务注解需要明确指定使用哪个事务管理器Service public class BusinessService { Autowired private UserMasterMapper userMasterMapper; // 自动注入主库Mapper Autowired private ReportSlaveMapper reportSlaveMapper; // 自动注入从库Mapper // 使用主库事务管理器 Transactional(transactionManager masterTransactionManager) public void createUserAndLog(User user) { userMasterMapper.insert(user); // ... 其他主库操作 } // 使用从库事务管理器。注意只读查询可以优化后面会讲 Transactional(transactionManager slaveTransactionManager, readOnly true) public ReportData generateReport(MapString, Object params) { return reportSlaveMapper.selectComplexReport(params); } }4. 进阶只读事务与事务传播的坑上面的Service示例中我们显式指定了transactionManager。但在只读查询场景下有更优的做法。4.1 为从库配置只读事务管理器我们可以为从库专门配置一个支持“只读”提示的事务管理器虽然DataSourceTransactionManager本身也支持readOnly属性但有些高级连接池或驱动能利用此提示进行优化。// 在SlaveDataSourceConfig中增加或替换 Bean(name slaveTransactionManager) public DataSourceTransactionManager slaveTransactionManager( Qualifier(slaveDataSource) DataSource dataSource) { DataSourceTransactionManager manager new DataSourceTransactionManager(dataSource); // 设置启用事务同步这对于某些需要线程绑定时资源如Spring的Transactional是好的默认值 manager.setEnforceReadOnly(true); // 强制实施只读提示可选 return manager; }然后在Service中使用readOnly trueTransactional(transactionManager slaveTransactionManager, readOnly true) public ReportData getReport() { // ... }4.2 多数据源事务的“大坑”与解决思路最核心的问题Transactional注解默认只管理一个事务管理器对应一个数据源的事务。如果你在一个Service方法中同时操作了多个数据源并希望它们作为一个原子事务要么都成功要么都回滚默认的声明式事务是做不到的。因为每个DataSourceTransactionManager只管理自己数据源上的连接。场景模拟Transactional(transactionManager masterTransactionManager) // 只管理master事务 public void crossDatabaseOperation() { userMasterMapper.insert(user); // 操作主库 reportSlaveMapper.insertLog(log); // 操作从库如果这里抛异常... }如果insertLog失败insert操作不会回滚因为从库的操作根本不在masterTransactionManager管理的事务内。解决方案避免跨库事务从设计上规避这是最根本的办法。重构业务逻辑确保一个事务边界内只操作一个数据库。如果需要数据一致性考虑使用消息队列最终一致性、分布式事务中间件如Seata或事后补偿机制。使用JTA分布式事务管理器在Spring Boot中整合Atomikos或Bitronix等JTA实现可以管理多个XADataSource的分布式事务。但这会带来显著的性能开销和复杂性非金融级强一致性需求一般不推荐。链式事务管理器ChainedTransactionManagerSpring Data提供了一个ChainedTransactionManager它可以按顺序管理多个事务管理器。但它实现的是“尽力而为”的提交协议并非真正的两阶段提交存在不一致的时间窗口使用时需充分了解其风险。实操心得在99%的业务场景下方案1避免跨库事务是最佳实践。在设计数据架构时就应尽量让一个业务单元的数据落在同一个数据库中。如果实在无法避免再谨慎评估是否真的需要强一致性或许最终一致性就能满足需求。5. 常见问题排查与性能优化实录配置多数据源后你可能会遇到以下问题5.1 启动报错Consider marking one of the beans as Primary问题描述应用启动失败控制台报错“Field * in * required a single bean, but 2 were found...”原因分析Spring容器中找到了多个DataSource或TransactionManager类型的Bean且你没有通过Qualifier指定注入哪一个Spring也无法自动选择因为没标记Primary。解决方案确保在你希望作为默认数据源的配置类对应的Bean上添加Primary注解通常是在主数据源的DataSource和TransactionManager上。在注入时使用Qualifier(“beanName”)明确指定要注入的Bean。例如在Slave的配置类中注入DataSource时就用Qualifier(“slaveDataSource”)。5.2 MyBatis Mapper扫描冲突或绑定错误问题描述Mapper接口被执行了两次或者执行SQL时提示连接了错误的数据库。原因分析主类上的MapperScan和自定义配置类上的MapperScan扫描范围有重叠。自定义配置类中的MapperScan没有正确指定sqlSessionFactoryRef导致Mapper使用了默认的可能是主数据源的SqlSessionFactory。解决方案移除主类上的MapperScan在显式多数据源配置中最佳实践是删除Spring Boot主应用类上的MapperScan注解完全由各个数据源配置类上的MapperScan来控制扫描和绑定。仔细检查包路径确保basePackages精确指向对应数据源的Mapper接口包没有重叠或遗漏。检查XML文件路径确保setMapperLocations指向的路径包含了正确的XML文件且XML中的namespace与Mapper接口全限定名一致。5.3 连接池资源耗尽或性能不佳问题描述应用运行一段时间后出现Connection is not available, request timed out after 30000ms等错误。原因分析连接池参数配置不合理或存在连接泄漏未正确关闭。排查与优化监控连接池启用HikariCP的日志监控在application.yml中添加logging: level: com.zaxxer.hikari.HikariConfig: DEBUG com.zaxxer.hikari: TRACE # 非常详细的连接池操作日志排查问题时开启查看日志中连接创建、借用、归还、淘汰的情况。合理设置参数maximum-pool-size: 不是越大越好。计算公式可参考连接数 ((核心数 * 2) 有效磁盘数)。对于Web应用初始值设在10-20之间观察。主库可略大于从库。minimum-idle: 设置和maximum-pool-size一样可以避免连接池伸缩带来的延迟但会一直占用数据库连接。生产环境通常小于maximum-pool-size。connection-timeout: 获取连接的超时时间默认30秒如果经常超时可能是maximum-pool-size太小或存在连接泄漏。idle-timeout和max-lifetime: 连接空闲和最大存活时间有助于清理僵死连接。需根据数据库服务端的wait_timeout设置建议略小于数据库服务端的设置。排查连接泄漏使用leak-detection-threshold参数如设为2000单位毫秒HikariCP会记录超过此时间未归还连接的堆栈信息帮助定位未关闭的Connection、Statement或ResultSet。5.4 动态数据源切换与事务嵌套的诡异问题如果你采用了AbstractRoutingDataSource方案并且配合Transactional使用可能会遇到切换失效的问题。典型场景Service public class ServiceA { Transactional public void methodA() { // 此时已经获取了默认数据源比如master的连接并开启了事务 DataSourceContextHolder.set(“slave”); // 尝试切换 someDao.queryFromSlave(); // 期望从slave查但实际可能还在用master的连接 } }原因Spring的事务管理器和Transactional注解在方法开始时就会根据当前的事务管理器或默认数据源获取一个数据库连接并将其绑定到当前线程ThreadLocal。在事务执行期间这个连接是复用的。因此在事务内部再调用DataSourceContextHolder.set()切换数据源键可能无法改变已经绑定的连接。解决方案切换点前置将数据源切换的操作放在事务边界之外。例如在调用methodA()之前就设置好数据源或者将需要不同数据源的操作拆分成不同的事务方法。使用AOP切面管理定义一个自定义注解如DataSource(“slave”)并编写一个AOP切面在进入目标方法之前Before切换数据源。确保切换发生在Spring事务拦截器获取连接之前。这需要仔细调整切面的执行顺序Order确保数据源切面在事务切面之前执行。查阅框架文档如果使用MyBatis-Plus多数据源其DS注解的事务处理逻辑已经过封装需严格按照其文档说明使用避免在复杂事务传播场景下出错。配置多数据源是Spring Boot项目从单体走向更复杂架构的常见一步。理解其原理谨慎处理事务边界合理规划数据存储才能让应用既灵活又稳健。
