做后端这些年只要业务稍微复杂一点“一个应用连一个库”的理想状态基本撑不住。用户数据放用户库、订单数据放订单库、日志又要独立一套再加上读写分离和多租户隔离的需求所有问题都指向同一个核心一个SpringBoot应用必须同时操作多个数据源。SpringBoot3发布之后我把手头几个老项目陆续升级上来才发现多数据源这件事远比想象中复杂——javax到jakarta的包名变更、自动配置机制的调整、旧版数据源工具的兼容问题一个接一个往外冒。这篇文章把我真实用过的几种方案、选型背后的逻辑、完整的配置过程和踩过的坑全部串一遍给正在SpringBoot3上折腾多数据源的你一份可以直接抄作业的参考。1. 哪些业务真的需要多数据源先想清楚再动手很多人一上来就问“多数据源怎么配”但很少有人先问“我到底为什么需要多数据源”。想清楚这个问题能帮你少买一半的教训。1.1 三种最常见的多库场景第一类是业务分库。举个例子某个电商项目用户信息、商品信息、订单数据放在同一个库里初期确实方便但一旦并发上来一个库的连接数、磁盘IO和锁竞争会把所有业务拖垮。于是拆成用户库、商品库、订单库应用层还要保持一套代码这时候就必须要有多数据源能力。第二类是读写分离。主库负责写从库负责读读流量是写流量的好几倍。代码层面不需要每个SQL都自己区分走哪个库而是通过数据源路由规则自动把查询请求分给从库。业务无感但性能提升明显。某积分系统就是典型的例子每天上百万的积分流水查询全部走从库主库负载降了一大截。第三类是跨库查询与数据隔离。比如运营后台要同时展示用户基础数据和用户行为日志但这两类数据存放在不同库中一个接口需要跨库读取。还有一种常见情况是做多租户系统租户A的数据在A库租户B的数据在B库应用启动时根本不知道当前请求属于哪个租户必须根据上下文动态决定连接哪个数据源。1.2 多数据源的代价也要提前想清楚多数据源不是银弹。每增加一个数据源就增加一份连接管理和事务协调的复杂度。最常见的连环坑有三个事务范围变难控制。一个业务方法如果横跨两个数据源Spring的本地事务就失效了要么接受数据最终一致要么引入分布式事务而分布式事务的代价非常大。运维和监控变复杂。每个库的连接数、慢查询、性能指标都要分开看否则出了问题根本不知道是哪一个库导致的。上线和变更风险更高。原来表结构变更只需要在一个库执行现在要同步到多个库版本管理一旦没做好很容易出现某个库已经更新、另一个库还停留在旧结构的情况。所以我的建议是能不分库就不分库能用单库加索引解决就别急着拆。真的拆了才认真考虑多数据源的技术选型。别为了炫技把一个单库能解决的问题搞成分布式难题。2. SpringBoot3时代的多数据源选型主流方案与取舍SpringBoot3比较大的变化是JavaEE换成了JakartaEE所以很多老的多数据源工具在它上面直接跑不起来。实际上面市场上有四条路线可以走各有各的适用边界。2.1 原生硬编码自己配置多个DataSource这种方案思路最直接。手动定义两个或更多DataSource Bean再分别为它们创建独立的SqlSessionFactory或JdbcTemplate然后在使用的地方显式注入对应的实例。Configuration public class DataSourceConfig { Bean(name masterDataSource) ConfigurationProperties(prefix spring.datasource.master) public DataSource masterDataSource() { return DataSourceBuilder.create().build(); } Bean(name slaveDataSource) ConfigurationProperties(prefix spring.datasource.slave) public DataSource slaveDataSource() { return DataSourceBuilder.create().build(); } }优点是从代码层面完全可控没有黑魔法出了问题一眼能定位。但缺点也很明显如果库很多或者切换频繁代码会膨胀得很难看。两个库各写一套Mapper甚至要维护两套SqlSessionFactory这种方案更适合数据源数量极少、切换场景基本固定的项目。维护成本高我一搬不推荐业务复杂的时候用。2.2 Spring原生AbstractRoutingDataSourceSpring本身提供了AbstractRoutingDataSource这个抽象类它本质上是一个路由中转站。我们可以在运行时通过determineCurrentLookupKey()方法返回一个键路由数据源会根据这个键选择真正对应的目标数据源。核心逻辑是public class DynamicDataSource extends AbstractRoutingDataSource { Override protected Object determineCurrentLookupKey() { return DynamicDataSourceContextHolder.getDataSourceKey(); } }使用ThreadLocal保存当前线程的路由键。当请求进来时在切面中设置key业务执行完后再清理掉。这套方案比硬编码灵活很多数据源可以按需扩展不用每个数据源都写死一套Mapper。但抽象类只解决“路由”的问题事务管理、分页插件识别、自动配置适配等问题全都得自己处理。也就是说它离“开箱即用”还有距离适合喜欢定制、愿意自己造轮子的团队。我用过一次后来发现需求一变就要改切面维护成本不低。2.3 dynamic-datasource轻量级动态数据源的主流之选这应该是国内目前用得最广泛的开源数据源路由方案。它基于AbstractRoutingDataSource做了封装把AOP切面、注解解析、连接切换、事务增强全部内置了。用户只需要在方法或类上加一个DS注解方法执行前自动切到指定数据源方法结束后自动切回主数据源。它的核心使用方式非常直观Service public class OrderService { DS(order-db) public ListOrder getOrderList() { return orderMapper.selectList(); } }在SpringBoot3下需要引入专门适配的starter后面会详细演示。这个方案的优点是轻量、上手快、代码侵入量小还有日志打印当前数据源key排查问题看得清楚。缺点就是它只解决多数据源“切换”这件事如果还需要分库分表、分布式事务得配合其他组件。2.4 ShardingSphere需要分库分表时的重量级选手当业务量已经大到需要分库分表比如订单表单表过亿那就不是单纯的多数据源问题而是数据分布策略的问题。ShardingSphere这类组件会用一套配置规则决定SQL应该路由到哪个库、哪张表它比多数据源框架的层级更高。ShardingSphere提供了数据分片、读写分离、数据脱敏、分布式事务等一整套能力。同样它也更复杂学习成本和运维成本都明显高于前几个方案。如果只是想在两个库之间切来切去用ShardingSphere就是把大炮打蚊子严重过度设计。2.5 选型对比与决策建议对比维度原生多DataSourceAbstractRoutingDataSourcedynamic-datasourceShardingSphere上手成本低中低高代码侵入高每多一个库写一套Bean中需要自研切面极低注解驱动低配置驱动切换灵活性差好非常好非常好事务支持需要自管需要自管提供DSTransactional自带分布式事务分库分表不支持不支持不支持支持SpringBoot3适配需自己确认需自己确认有专门starter有专门starter适用场景数据源极少且固定喜欢定制的中型项目绝大多数业务系统数据量大且需分片我的建议是普通业务系统优先考虑dynamic-datasource它把99%的多数据源切换需求都覆盖了文档和资料都比较全。如果团队习惯原生写法且数据源不超过两个用AbstractRoutingDataSource自己包一层也可以。真到了必须分库分表的阶段直接引入ShardingSphere尽量别自己造分片轮子。做技术选型时把“最少代码完成最多需求”作为第一原则多数的纠结都会变得明朗。3. 实操落地SpringBoot3 dynamic-datasource从零配置既然当前多数场景下dynamic-datasource是性价比最高的选择我就用这套方案完整演示一遍从引入依赖到跑通接口的整个过程。版本基于SpringBoot3这一点非常关键。3.1 依赖引入与SpringBoot3适配SpringBoot3最大的坑是javax变成了jakarta导致很多老框架的旧版本无法直接使用。dynamic-datasource在3.x版本时代是为SpringBoot2设计的到了SpringBoot3必须引入专门提供适配的starter。我当前项目使用的方式是dependency groupIdcom.baomidou/groupId artifactIddynamic-datasource-spring-boot3-starter/artifactId version4.2.0/version /dependency注意artifactId里一定要有spring-boot3字样。引入这个之后MyBatis相关依赖也尽量采用mybatis-plus或mybatis-spring的SpringBoot3适配版本否则运行期容易因为类加载顺序问题出现各种奇怪异常。我就曾经因为MyBatis版本太老导致数据源初始化时报“Error creating bean with name sqlSessionFactory”排查了一个晚上才发现是版本兼容问题。3.2 多数据源核心配置与代码实现先看配置文件。假设业务需要连接两个库分别是主库master-db和订单库order-dbspring: datasource: dynamic: primary: master strict: true datasource: master: url: jdbc:mysql://localhost:3306/master_db?useUnicodetruecharacterEncodingUTF-8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver order-db: url: jdbc:mysql://localhost:3306/order_db?useUnicodetruecharacterEncodingUTF-8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driverprimary指定默认数据源严格模式strict如果设为true使用一个不存在的DS名称会直接抛异常它能帮你尽早暴露配置写错的问题所以我建议生产环境一定开strict。然后写一个Mapper放在一个独立的包下DS(order-db) Mapper public interface OrderMapper { ListOrder selectOrderList(); }这个DS加在接口上表示这个Mapper的所有操作都走order-db。如果某个方法需要临时走主库可以在方法上再加DS覆盖类上的配置。Service层同样可以精确控制Service public class OrderQueryService { private final OrderMapper orderMapper; public OrderQueryService(OrderMapper orderMapper) { this.orderMapper orderMapper; } DS(order-db) public ListOrder queryFromOrderDb() { return orderMapper.selectOrderList(); } DS(master) public Order queryFromMaster(Long id) { return orderMapper.selectById(id); } }实测下来dynamic-datasource的AOP切换是非常精准的进入方法时把key放入ThreadLocal方法结束时移除key。但要注意如果你在一个Service方法里调用了另一个类的方法并且对方也标了DS那切换规则会以后者为准。这种“隐式覆盖”很容易让人误判排查时一定要结合日志中打印的“dynamic-datasource switch to ...”信息来确认实际走到了哪个库。3.3 事务边界与DSTransactional的正确用法多数据源最容易搞出事故的就是事务。Spring的Transactional基于DataSourceTransactionManager事务管理器在启动时就绑定了数据源。如果你在方法上同时标了Transactional和DS指望事务方法内自由切换数据源那基本是白日做梦。来看一个典型反例Transactional DS(order-db) public void updateOrderAndUser() { orderMapper.updateOrder(); userMapper.updateUser(); // 这个Mapper默认走master }实际运行后DS会先把数据源切到order-db但Transactional准备工作拿连接时拿到的连接只对应order-db。userMapper虽然本身配置走master但因为当前线程已经绑定了order-db的连接所以它的SQL依然会发往order-db数据落到了错误的库里。解决方案是在跨数据源操作的场景下不要使用Spring原生事务改成dynamic-datasource提供的DSTransactionalDSTransactional public void updateOrderAndUser() { orderMapper.updateOrder(); userMapper.updateUser(); }DSTransactional内部自己管理多数据源连接能让同一个方法里不同Mapper分别拿到各自对应的连接然后再统一提交或回滚。它本质上是通过自定义事务控制来实现多库一致性但同时也要说明这不等于分布式强一致性事务如果对一致性要求极高比如资金相关场景还是得考虑引入可靠的消息或分布式事务组件。另外一个更容易被忽视的点是由于DSTransactional自己接管了事务生命周期它不支持在同一个方法中嵌套调用另一个标有Spring原生Transactional的方法否则事务控制会出现重叠回滚行为无法预料。团队里如果有新同学建议在规范里明确多数据源场景一律用DSTransactional原生Transactional只留给单数据源场景。4. 多数据源避坑实录那些文档没写清楚的细节配置能跑通只是第一步真正熬人的是上线之后的疑难杂症。这些坑我基本都踩过每一条都是拿线上事故换来的经验。4.1 事务内切换数据源为什么会失效这个前面已经展开讲过再补充一个更隐蔽的例子。即使你的方法没有加Transactional如果在同一个线程里某个框架组件内部偷偷绑定了连接也会导致DS切换失效。比如Spring事件监听器里拉取数据、定时任务里跨方法调用、或者在一个已有的业务事务回调里继续执行SQL。我遇到过的一个Case是一个订单导出功能在一个被Transactional包裹的大事务里调用了一个工具类工具类里的查询标了DS(order-db)结果这个查询还是落到了主库。原因是外部事务已经通过主数据源连接执行过SQL连接被绑定到了当前线程DS切换只能改路由键但要拿新连接时发现线程已经有主库连接于是直接复用了。排查方法很简单打开dynamic-datasource的日志观察每一个SQL执行前打印的数据源key对比实际连接的数据库名。一旦发现key切了但连接没换就去查方法的调用链看是否掉进了Spring事务包裹的范围。4.2 分页插件、主键生成与连接池的坑分页是另一个高频翻车点。MyBatis的分页插件PageHelper在单数据源下很好用但多数据源下如果设置方言不正确或者分页插件先于路由初始化就会导致分页SQL发到了错误的数据源上。SpringBoot3下记得使用适配版本并显式指定数据库方言。主键生成也需要留意。不同数据源的主键策略并不一样。某次我把一个旧项目从单库拆成用户库和订单库结果订单库的表还沿用了自增ID而用户库已经改成了雪花ID。虽然应用层没报错但后续合并报表时两边ID语义完全不一致导致数据对不上。在多数据源架构里建议所有业务表统一使用分布式ID生成策略避免把数据源的主键特性写死在业务代码里。连接池方面dynamic-datasource本身不负责创建连接池它会用配置中指定的连接池实现。SpringBoot3默认HikariCP如果后续想用Druid需要单独引入适配依赖并且把配置项从spring.datasource.hikari改为spring.datasource.druid开头。混用多个连接池实现也可以但会显著增加排查难度我个人的经验是统一用一种连接池。4.3 初始化顺序与自动配置失效的排查SpringBoot3的自动配置机制和SpringBoot2差别不小老项目升级上来后经常遇到的一个现象是某些Bean已经定义但就是不生效或者报“Failed to configure a DataSource”错误。这个报错通常意味着Spring没有找到可用的DataSource。在多数据源项目中一个比较常见的原因是配置了dynamic-datasource却又额外引入了一个不相关的DataSource自动配置类比如某些第三方starter会偷偷创建一个DataSourceCreator。SpringBoot3下如果不小心引入了一个为SpringBoot2设计的旧版starter它的自动配置类在spring.factories里声明新版根本不会读取于是预期该生效的DataSource没有创建。排查这类问题我一般的步骤是先看启动日志中是否有AutoConfiguration相关的排除记录。再看spring.datasource.dynamic配置是否真正被加载如果无法确认加一个ConfigurationProperties注册类把配置绑定结果打印出来。最后检查依赖树找出那些间接引入的DataSource相关包。记得有一次项目里只是多了一个报警组件依赖它的自动配置抢先创建了一个空DataSource导致整个应用启动报错。解决办法是在启动类上用exclude属性排除那个自动配置类或者干脆去掉多余依赖。这类问题往往比业务代码bug更难发现因为它看不见摸不着只能靠依赖分析和日志层层扒。5. 常见故障排查速查表多数据源的问题花样多但规律性也强。我把高频故障按表现、可能原因和解决思路整理成了一张速查表排查时可以直接对照。5.1 典型报错与解决思路故障现象常见原因解决思路启动报Failed to configure a DataSource多数据源配置未生效或第三方starter抢先创建了DataSource检查依赖树排除多余的DataSource自动配置类确认dynamic配置被加载DS注解不生效SQL全部落主库AOP未被拦截类没有被Spring管理或方法自调用确认Mapper/Service是注入的Bean避免同类内部方法直接调用改用注入对象事务里切库失败数据落错库外部Transactional绑定了旧连接ThreadLocal连接被复用改成DSTransactional或调整事务边界分页SQL方言错误或无法分页PageHelper版本不适配SpringBoot3或方言未配置升级适配版本显式设置方言检查拦截器顺序同一数据源连接池爆满数据源连接数配置过小或慢SQL过多分开监控每个库的连接池优化慢SQL调大max-pool-size切换数据源后查询报“表不存在”路由到的库确实没有对应表或者表结构不一致核对DS里的key与配置中的数据源名称检查库表结构主从延迟导致刚写入读不到读写分离场景下从库同步延迟关键链路强制走主库或引入短时缓存这张表只是排查的起点真正的难点在于日志里往往不会直接告诉你“我是因为连接被绑定才选错库”。还是那句老话先用日志定位“当前SQL实际连到了哪个库”再倒推为什么。5.2 我常用的排查路径排查多数据源问题我有一套固定动作效率比乱试配置高很多。打开dynamic-datasource的日志级别调整为debug观察运行时打印的switch日志。这一步能最快确认路由是否如预期执行。在容易出问题的方法里临时加一行日志打印当前数据源key和目标SQL的表名确认代码层面的意图。如果怀疑是事务连接绑定可以用DataSourceUtils.getConnection把当前线程绑定连接打印出来对比它的jdbcUrl。但这步只能临时排查不能长期保留在代码里。最后才去查依赖版本和自动配置大多数时候问题都会在前两步就水落石出。这套顺序的核心逻辑是先证明代码走到了哪一步再看环境配置为什么没跟上而不是颠倒过来瞎猜。6. 写在最后几条实战心得多数据源这件事配置本身只是冰山一角真正的复杂度在事务边界、连接管理和团队约定上。我个人的体会是最容易出问题的不是新手不会写DS而是老项目在重构时把多数据源强塞进了一个原本单数据源的事务模型中结果上线即事故。如果让我给几个关键建议第一是所有数据源名称和业务归属必须在文档里写清楚不能只存在代码注解里。第二是全国统一使用一种连接池实现别这个库Hikari那个库Druid出问题时排查成本和复杂度都会成倍增长。第三是上线前一定要补一个跨数据源查询的集成测试把主从路由、事务回滚、分页查询三条链路全部覆盖到。多数据源方案选定后后续还可以继续扩展多租户隔离、读写分离、分片路由等能力当然这些都是后话。先把最小可运行的方案跑通再一步步加固这条路走起来会稳得多。最后再分享一个小技巧给动态数据源开启日志后在开发环境把输出格式做成一行一个关键字段比如“当前线程ID 数据源key SQL摘要”这样无论是自己调试还是让同事帮忙排查都能省掉大量沟通成本。这个习惯我保留了很久也让我少背了好几次锅。
做后端这些年只要业务稍微复杂一点“一个应用连一个库”的理想状态基本撑不住。用户数据放用户库、订单数据放订单库、日志又要独立一套再加上读写分离和多租户隔离的需求所有问题都指向同一个核心一个SpringBoot应用必须同时操作多个数据源。SpringBoot3发布之后我把手头几个老项目陆续升级上来才发现多数据源这件事远比想象中复杂——javax到jakarta的包名变更、自动配置机制的调整、旧版数据源工具的兼容问题一个接一个往外冒。这篇文章把我真实用过的几种方案、选型背后的逻辑、完整的配置过程和踩过的坑全部串一遍给正在SpringBoot3上折腾多数据源的你一份可以直接抄作业的参考。1. 哪些业务真的需要多数据源先想清楚再动手很多人一上来就问“多数据源怎么配”但很少有人先问“我到底为什么需要多数据源”。想清楚这个问题能帮你少买一半的教训。1.1 三种最常见的多库场景第一类是业务分库。举个例子某个电商项目用户信息、商品信息、订单数据放在同一个库里初期确实方便但一旦并发上来一个库的连接数、磁盘IO和锁竞争会把所有业务拖垮。于是拆成用户库、商品库、订单库应用层还要保持一套代码这时候就必须要有多数据源能力。第二类是读写分离。主库负责写从库负责读读流量是写流量的好几倍。代码层面不需要每个SQL都自己区分走哪个库而是通过数据源路由规则自动把查询请求分给从库。业务无感但性能提升明显。某积分系统就是典型的例子每天上百万的积分流水查询全部走从库主库负载降了一大截。第三类是跨库查询与数据隔离。比如运营后台要同时展示用户基础数据和用户行为日志但这两类数据存放在不同库中一个接口需要跨库读取。还有一种常见情况是做多租户系统租户A的数据在A库租户B的数据在B库应用启动时根本不知道当前请求属于哪个租户必须根据上下文动态决定连接哪个数据源。1.2 多数据源的代价也要提前想清楚多数据源不是银弹。每增加一个数据源就增加一份连接管理和事务协调的复杂度。最常见的连环坑有三个事务范围变难控制。一个业务方法如果横跨两个数据源Spring的本地事务就失效了要么接受数据最终一致要么引入分布式事务而分布式事务的代价非常大。运维和监控变复杂。每个库的连接数、慢查询、性能指标都要分开看否则出了问题根本不知道是哪一个库导致的。上线和变更风险更高。原来表结构变更只需要在一个库执行现在要同步到多个库版本管理一旦没做好很容易出现某个库已经更新、另一个库还停留在旧结构的情况。所以我的建议是能不分库就不分库能用单库加索引解决就别急着拆。真的拆了才认真考虑多数据源的技术选型。别为了炫技把一个单库能解决的问题搞成分布式难题。2. SpringBoot3时代的多数据源选型主流方案与取舍SpringBoot3比较大的变化是JavaEE换成了JakartaEE所以很多老的多数据源工具在它上面直接跑不起来。实际上面市场上有四条路线可以走各有各的适用边界。2.1 原生硬编码自己配置多个DataSource这种方案思路最直接。手动定义两个或更多DataSource Bean再分别为它们创建独立的SqlSessionFactory或JdbcTemplate然后在使用的地方显式注入对应的实例。Configuration public class DataSourceConfig { Bean(name masterDataSource) ConfigurationProperties(prefix spring.datasource.master) public DataSource masterDataSource() { return DataSourceBuilder.create().build(); } Bean(name slaveDataSource) ConfigurationProperties(prefix spring.datasource.slave) public DataSource slaveDataSource() { return DataSourceBuilder.create().build(); } }优点是从代码层面完全可控没有黑魔法出了问题一眼能定位。但缺点也很明显如果库很多或者切换频繁代码会膨胀得很难看。两个库各写一套Mapper甚至要维护两套SqlSessionFactory这种方案更适合数据源数量极少、切换场景基本固定的项目。维护成本高我一搬不推荐业务复杂的时候用。2.2 Spring原生AbstractRoutingDataSourceSpring本身提供了AbstractRoutingDataSource这个抽象类它本质上是一个路由中转站。我们可以在运行时通过determineCurrentLookupKey()方法返回一个键路由数据源会根据这个键选择真正对应的目标数据源。核心逻辑是public class DynamicDataSource extends AbstractRoutingDataSource { Override protected Object determineCurrentLookupKey() { return DynamicDataSourceContextHolder.getDataSourceKey(); } }使用ThreadLocal保存当前线程的路由键。当请求进来时在切面中设置key业务执行完后再清理掉。这套方案比硬编码灵活很多数据源可以按需扩展不用每个数据源都写死一套Mapper。但抽象类只解决“路由”的问题事务管理、分页插件识别、自动配置适配等问题全都得自己处理。也就是说它离“开箱即用”还有距离适合喜欢定制、愿意自己造轮子的团队。我用过一次后来发现需求一变就要改切面维护成本不低。2.3 dynamic-datasource轻量级动态数据源的主流之选这应该是国内目前用得最广泛的开源数据源路由方案。它基于AbstractRoutingDataSource做了封装把AOP切面、注解解析、连接切换、事务增强全部内置了。用户只需要在方法或类上加一个DS注解方法执行前自动切到指定数据源方法结束后自动切回主数据源。它的核心使用方式非常直观Service public class OrderService { DS(order-db) public ListOrder getOrderList() { return orderMapper.selectList(); } }在SpringBoot3下需要引入专门适配的starter后面会详细演示。这个方案的优点是轻量、上手快、代码侵入量小还有日志打印当前数据源key排查问题看得清楚。缺点就是它只解决多数据源“切换”这件事如果还需要分库分表、分布式事务得配合其他组件。2.4 ShardingSphere需要分库分表时的重量级选手当业务量已经大到需要分库分表比如订单表单表过亿那就不是单纯的多数据源问题而是数据分布策略的问题。ShardingSphere这类组件会用一套配置规则决定SQL应该路由到哪个库、哪张表它比多数据源框架的层级更高。ShardingSphere提供了数据分片、读写分离、数据脱敏、分布式事务等一整套能力。同样它也更复杂学习成本和运维成本都明显高于前几个方案。如果只是想在两个库之间切来切去用ShardingSphere就是把大炮打蚊子严重过度设计。2.5 选型对比与决策建议对比维度原生多DataSourceAbstractRoutingDataSourcedynamic-datasourceShardingSphere上手成本低中低高代码侵入高每多一个库写一套Bean中需要自研切面极低注解驱动低配置驱动切换灵活性差好非常好非常好事务支持需要自管需要自管提供DSTransactional自带分布式事务分库分表不支持不支持不支持支持SpringBoot3适配需自己确认需自己确认有专门starter有专门starter适用场景数据源极少且固定喜欢定制的中型项目绝大多数业务系统数据量大且需分片我的建议是普通业务系统优先考虑dynamic-datasource它把99%的多数据源切换需求都覆盖了文档和资料都比较全。如果团队习惯原生写法且数据源不超过两个用AbstractRoutingDataSource自己包一层也可以。真到了必须分库分表的阶段直接引入ShardingSphere尽量别自己造分片轮子。做技术选型时把“最少代码完成最多需求”作为第一原则多数的纠结都会变得明朗。3. 实操落地SpringBoot3 dynamic-datasource从零配置既然当前多数场景下dynamic-datasource是性价比最高的选择我就用这套方案完整演示一遍从引入依赖到跑通接口的整个过程。版本基于SpringBoot3这一点非常关键。3.1 依赖引入与SpringBoot3适配SpringBoot3最大的坑是javax变成了jakarta导致很多老框架的旧版本无法直接使用。dynamic-datasource在3.x版本时代是为SpringBoot2设计的到了SpringBoot3必须引入专门提供适配的starter。我当前项目使用的方式是dependency groupIdcom.baomidou/groupId artifactIddynamic-datasource-spring-boot3-starter/artifactId version4.2.0/version /dependency注意artifactId里一定要有spring-boot3字样。引入这个之后MyBatis相关依赖也尽量采用mybatis-plus或mybatis-spring的SpringBoot3适配版本否则运行期容易因为类加载顺序问题出现各种奇怪异常。我就曾经因为MyBatis版本太老导致数据源初始化时报“Error creating bean with name sqlSessionFactory”排查了一个晚上才发现是版本兼容问题。3.2 多数据源核心配置与代码实现先看配置文件。假设业务需要连接两个库分别是主库master-db和订单库order-dbspring: datasource: dynamic: primary: master strict: true datasource: master: url: jdbc:mysql://localhost:3306/master_db?useUnicodetruecharacterEncodingUTF-8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver order-db: url: jdbc:mysql://localhost:3306/order_db?useUnicodetruecharacterEncodingUTF-8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driverprimary指定默认数据源严格模式strict如果设为true使用一个不存在的DS名称会直接抛异常它能帮你尽早暴露配置写错的问题所以我建议生产环境一定开strict。然后写一个Mapper放在一个独立的包下DS(order-db) Mapper public interface OrderMapper { ListOrder selectOrderList(); }这个DS加在接口上表示这个Mapper的所有操作都走order-db。如果某个方法需要临时走主库可以在方法上再加DS覆盖类上的配置。Service层同样可以精确控制Service public class OrderQueryService { private final OrderMapper orderMapper; public OrderQueryService(OrderMapper orderMapper) { this.orderMapper orderMapper; } DS(order-db) public ListOrder queryFromOrderDb() { return orderMapper.selectOrderList(); } DS(master) public Order queryFromMaster(Long id) { return orderMapper.selectById(id); } }实测下来dynamic-datasource的AOP切换是非常精准的进入方法时把key放入ThreadLocal方法结束时移除key。但要注意如果你在一个Service方法里调用了另一个类的方法并且对方也标了DS那切换规则会以后者为准。这种“隐式覆盖”很容易让人误判排查时一定要结合日志中打印的“dynamic-datasource switch to ...”信息来确认实际走到了哪个库。3.3 事务边界与DSTransactional的正确用法多数据源最容易搞出事故的就是事务。Spring的Transactional基于DataSourceTransactionManager事务管理器在启动时就绑定了数据源。如果你在方法上同时标了Transactional和DS指望事务方法内自由切换数据源那基本是白日做梦。来看一个典型反例Transactional DS(order-db) public void updateOrderAndUser() { orderMapper.updateOrder(); userMapper.updateUser(); // 这个Mapper默认走master }实际运行后DS会先把数据源切到order-db但Transactional准备工作拿连接时拿到的连接只对应order-db。userMapper虽然本身配置走master但因为当前线程已经绑定了order-db的连接所以它的SQL依然会发往order-db数据落到了错误的库里。解决方案是在跨数据源操作的场景下不要使用Spring原生事务改成dynamic-datasource提供的DSTransactionalDSTransactional public void updateOrderAndUser() { orderMapper.updateOrder(); userMapper.updateUser(); }DSTransactional内部自己管理多数据源连接能让同一个方法里不同Mapper分别拿到各自对应的连接然后再统一提交或回滚。它本质上是通过自定义事务控制来实现多库一致性但同时也要说明这不等于分布式强一致性事务如果对一致性要求极高比如资金相关场景还是得考虑引入可靠的消息或分布式事务组件。另外一个更容易被忽视的点是由于DSTransactional自己接管了事务生命周期它不支持在同一个方法中嵌套调用另一个标有Spring原生Transactional的方法否则事务控制会出现重叠回滚行为无法预料。团队里如果有新同学建议在规范里明确多数据源场景一律用DSTransactional原生Transactional只留给单数据源场景。4. 多数据源避坑实录那些文档没写清楚的细节配置能跑通只是第一步真正熬人的是上线之后的疑难杂症。这些坑我基本都踩过每一条都是拿线上事故换来的经验。4.1 事务内切换数据源为什么会失效这个前面已经展开讲过再补充一个更隐蔽的例子。即使你的方法没有加Transactional如果在同一个线程里某个框架组件内部偷偷绑定了连接也会导致DS切换失效。比如Spring事件监听器里拉取数据、定时任务里跨方法调用、或者在一个已有的业务事务回调里继续执行SQL。我遇到过的一个Case是一个订单导出功能在一个被Transactional包裹的大事务里调用了一个工具类工具类里的查询标了DS(order-db)结果这个查询还是落到了主库。原因是外部事务已经通过主数据源连接执行过SQL连接被绑定到了当前线程DS切换只能改路由键但要拿新连接时发现线程已经有主库连接于是直接复用了。排查方法很简单打开dynamic-datasource的日志观察每一个SQL执行前打印的数据源key对比实际连接的数据库名。一旦发现key切了但连接没换就去查方法的调用链看是否掉进了Spring事务包裹的范围。4.2 分页插件、主键生成与连接池的坑分页是另一个高频翻车点。MyBatis的分页插件PageHelper在单数据源下很好用但多数据源下如果设置方言不正确或者分页插件先于路由初始化就会导致分页SQL发到了错误的数据源上。SpringBoot3下记得使用适配版本并显式指定数据库方言。主键生成也需要留意。不同数据源的主键策略并不一样。某次我把一个旧项目从单库拆成用户库和订单库结果订单库的表还沿用了自增ID而用户库已经改成了雪花ID。虽然应用层没报错但后续合并报表时两边ID语义完全不一致导致数据对不上。在多数据源架构里建议所有业务表统一使用分布式ID生成策略避免把数据源的主键特性写死在业务代码里。连接池方面dynamic-datasource本身不负责创建连接池它会用配置中指定的连接池实现。SpringBoot3默认HikariCP如果后续想用Druid需要单独引入适配依赖并且把配置项从spring.datasource.hikari改为spring.datasource.druid开头。混用多个连接池实现也可以但会显著增加排查难度我个人的经验是统一用一种连接池。4.3 初始化顺序与自动配置失效的排查SpringBoot3的自动配置机制和SpringBoot2差别不小老项目升级上来后经常遇到的一个现象是某些Bean已经定义但就是不生效或者报“Failed to configure a DataSource”错误。这个报错通常意味着Spring没有找到可用的DataSource。在多数据源项目中一个比较常见的原因是配置了dynamic-datasource却又额外引入了一个不相关的DataSource自动配置类比如某些第三方starter会偷偷创建一个DataSourceCreator。SpringBoot3下如果不小心引入了一个为SpringBoot2设计的旧版starter它的自动配置类在spring.factories里声明新版根本不会读取于是预期该生效的DataSource没有创建。排查这类问题我一般的步骤是先看启动日志中是否有AutoConfiguration相关的排除记录。再看spring.datasource.dynamic配置是否真正被加载如果无法确认加一个ConfigurationProperties注册类把配置绑定结果打印出来。最后检查依赖树找出那些间接引入的DataSource相关包。记得有一次项目里只是多了一个报警组件依赖它的自动配置抢先创建了一个空DataSource导致整个应用启动报错。解决办法是在启动类上用exclude属性排除那个自动配置类或者干脆去掉多余依赖。这类问题往往比业务代码bug更难发现因为它看不见摸不着只能靠依赖分析和日志层层扒。5. 常见故障排查速查表多数据源的问题花样多但规律性也强。我把高频故障按表现、可能原因和解决思路整理成了一张速查表排查时可以直接对照。5.1 典型报错与解决思路故障现象常见原因解决思路启动报Failed to configure a DataSource多数据源配置未生效或第三方starter抢先创建了DataSource检查依赖树排除多余的DataSource自动配置类确认dynamic配置被加载DS注解不生效SQL全部落主库AOP未被拦截类没有被Spring管理或方法自调用确认Mapper/Service是注入的Bean避免同类内部方法直接调用改用注入对象事务里切库失败数据落错库外部Transactional绑定了旧连接ThreadLocal连接被复用改成DSTransactional或调整事务边界分页SQL方言错误或无法分页PageHelper版本不适配SpringBoot3或方言未配置升级适配版本显式设置方言检查拦截器顺序同一数据源连接池爆满数据源连接数配置过小或慢SQL过多分开监控每个库的连接池优化慢SQL调大max-pool-size切换数据源后查询报“表不存在”路由到的库确实没有对应表或者表结构不一致核对DS里的key与配置中的数据源名称检查库表结构主从延迟导致刚写入读不到读写分离场景下从库同步延迟关键链路强制走主库或引入短时缓存这张表只是排查的起点真正的难点在于日志里往往不会直接告诉你“我是因为连接被绑定才选错库”。还是那句老话先用日志定位“当前SQL实际连到了哪个库”再倒推为什么。5.2 我常用的排查路径排查多数据源问题我有一套固定动作效率比乱试配置高很多。打开dynamic-datasource的日志级别调整为debug观察运行时打印的switch日志。这一步能最快确认路由是否如预期执行。在容易出问题的方法里临时加一行日志打印当前数据源key和目标SQL的表名确认代码层面的意图。如果怀疑是事务连接绑定可以用DataSourceUtils.getConnection把当前线程绑定连接打印出来对比它的jdbcUrl。但这步只能临时排查不能长期保留在代码里。最后才去查依赖版本和自动配置大多数时候问题都会在前两步就水落石出。这套顺序的核心逻辑是先证明代码走到了哪一步再看环境配置为什么没跟上而不是颠倒过来瞎猜。6. 写在最后几条实战心得多数据源这件事配置本身只是冰山一角真正的复杂度在事务边界、连接管理和团队约定上。我个人的体会是最容易出问题的不是新手不会写DS而是老项目在重构时把多数据源强塞进了一个原本单数据源的事务模型中结果上线即事故。如果让我给几个关键建议第一是所有数据源名称和业务归属必须在文档里写清楚不能只存在代码注解里。第二是全国统一使用一种连接池实现别这个库Hikari那个库Druid出问题时排查成本和复杂度都会成倍增长。第三是上线前一定要补一个跨数据源查询的集成测试把主从路由、事务回滚、分页查询三条链路全部覆盖到。多数据源方案选定后后续还可以继续扩展多租户隔离、读写分离、分片路由等能力当然这些都是后话。先把最小可运行的方案跑通再一步步加固这条路走起来会稳得多。最后再分享一个小技巧给动态数据源开启日志后在开发环境把输出格式做成一行一个关键字段比如“当前线程ID 数据源key SQL摘要”这样无论是自己调试还是让同事帮忙排查都能省掉大量沟通成本。这个习惯我保留了很久也让我少背了好几次锅。
