做 Java 后端的同学十有八九都会遇到“动态数据源切换失效”这种怪事。代码里明明把数据源 key 设置成了从库执行查询后一打日志走的还是主库或者第一次正常第二次直接串库还有一种更隐蔽的同一个方法里前几行查询走从库加了一个事务注解之后整段逻辑全跑回主库。这类问题在 Spring 项目里太典型了表现形式千奇百怪但追到根子上基本都是同一个矛盾Spring 的数据源切换是一个基于调用链的行为而连接Connection却是按事务边界缓存和复用的。这篇文章结合我实际排查过的几个案例把 Spring 动态数据源切换失效的底层原理、典型场景、定位方法以及一套稳定写法完整拆一遍适合用过AbstractRoutingDataSource但一直被切换问题困扰的同学。1. 动态数据源切换失效先把底层原理说透1.1 动态数据源是怎么做到按需切换的Spring 里做动态数据源绝大多数项目都会选择AbstractRoutingDataSource。它内部维护了一个MapObject, Object形式的targetDataSources每次调用getConnection()时都会先执行determineCurrentLookupKey()用返回的 key 去这个 Map 里找对应的物理 DataSource。常见的实现大概是这个样子public class DynamicDataSource extends AbstractRoutingDataSource { Override protected Object determineCurrentLookupKey() { return DynamicDataSourceContextHolder.get(); } }而DynamicDataSourceContextHolder本质上就是一个 ThreadLocalpublic class DynamicDataSourceContextHolder { private static final ThreadLocalString CONTEXT new ThreadLocal(); public static void set(String key) { CONTEXT.set(key); } public static String get() { return CONTEXT.get(); } public static void clear() { CONTEXT.remove(); } }这个设计看起来非常优雅DataSource.getConnection()是任何一次数据库操作的必经之路只要 key 在调用链路上被正确设置连接自然就从目标数据源拿。问题是很多人忽略了AbstractRoutingDataSource只在 getConnection 的时候才去读 key而 Spring 里触发getConnection()的时机往往不在你的业务代码里而是在事务管理器里。1.2 连接生命周期切换的不是数据源而是“下一次连接”Spring 的事务管理模型是同一个事务内只在一个物理连接上工作。事务开启后所有 DAO 操作都复用绑定在当前线程上的那个 Connection这个绑定关系由TransactionSynchronizationManager维护。关键点在于声明式事务开启的时候Spring 并不会等到你第一个 Mapper 方法执行才去拿连接。很多场景下事务管理器在执行目标方法之前就已经通过DataSourceUtils.getConnection(dataSource)把连接拿到手了。一旦连接被拿到并且被绑定到当前线程后面再设置动态数据源 key都已经太晚了。已经拿出来的连接不会因为你改了 key 就换一把它只会继续在当前事务里被复用。可以类比成电梯你在进入电梯前选楼层楼层才有效。启动事务就像人已经进了电梯这时候不管按多少次别的楼层按钮电梯都不会换另一台它只会把你送到当前这台电梯里已经选定的楼层。动态数据源切换也一样决定结果的是set(key) 和 getConnection() 谁先谁后。1.3 为什么注解执行了、key 也对了还是没切换成功很多排查过程卡在这里明明在切面里打了日志key 确实被设置成slave了为什么后面执行的 SQL 还是走主库原因很简单key 设置对了不代表连接是在设置之后才获取的。如果连接是在切面设置 key 之前就被事务管理器拿走了那后续所有 SQL 都只会看到那个已经被绑定的连接。更准确地说AbstractRoutingDataSource.determineCurrentLookupKey()只会影响“下一次获取连接”的时机它左右不了“已经存在的连接”。所以判断一个动态数据源切换到底有没有生效不能只看 key 有没有设置进去而要看完整的时序key 的设置必须发生在连接获取之前并且连接获取必须发生在同一个线程里。这个结论是后面所有定位工作的总原则。2. 四个最容易让动态数据源切换失效的场景2.1 事务先于切源运行key 等于是摆在了终点线后面最典型的一种写法就是这样Transactional(readOnly true) public Order queryOrder(String orderId) { DynamicDataSourceContextHolder.set(slave); return orderMapper.selectById(orderId); }看起来没什么问题方法一开始设置了数据源 key然后执行查询。但问题是Transactional在方法进入时就已经启动了事务而事务启动的瞬间事务管理器可能就已经把连接拿到了。等到方法体里执行DynamicDataSourceContextHolder.set(slave)时连接早就绑定在当前线程上了这个 key 只是“白设置”了。这种场景在读写分离项目里极其常见。很多人一开始不用事务时切换一切正常后来因为业务需要加了个Transactional动态数据源立刻失效。原因就是连接获取的时机被事务提前了。正确的思路是把切源和事务拉开先设置 key再进入事务边界。最推荐的方式是拆成两个方法把设置 key 的入口放在不带事务的外层方法public Order queryOrder(String orderId) { DynamicDataSourceContextHolder.set(slave); try { return queryOrderInTx(orderId); } finally { DynamicDataSourceContextHolder.clear(); } } Transactional(readOnly true) public Order queryOrderInTx(String orderId) { return orderMapper.selectById(orderId); }不过这里要注意如果这两个方法在同一个类里外层方法调用内层方法时是this直接调用Transactional会被代理机制绕过内层方法的事务不生效所以最好把queryOrderInTx放到另一个 Spring Bean 里或者使用AopContext.currentProxy()。2.2 切面顺序不对动态数据源切面被事务拦截器抢了先注解方式的动态数据源切换本质上是 AOP。Spring 容器里同时存在事务拦截器和自定义数据源切面时它们的执行顺序是影响切换结果的另一个关键变量。如果自定义数据源切面的执行顺序在事务拦截器的后面事务拦截器先把连接拿了数据源切面再设置 key就晚了。所以动态数据源切面必须明确地指定一个高优先级Aspect Component Order(Ordered.HIGHEST_PRECEDENCE) public class DynamicDataSourceAspect { Around(annotation(dataSourceKey)) public Object switchDataSource(ProceedingJoinPoint joinPoint, DataSourceKey dataSourceKey) throws Throwable { DynamicDataSourceContextHolder.set(dataSourceKey.value()); try { return joinPoint.proceed(); } finally { DynamicDataSourceContextHolder.clear(); } } }Order(Ordered.HIGHEST_PRECEDENCE)保证这个切面比 Spring 默认的事务拦截器先执行。如果项目里还有别的 AOP比如缓存、日志、权限校验也要注意顺序。数据源切换不是越早越好但必须保证早于任何可能触发getConnection()的拦截器。2.3 多线程和异步任务ThreadLocal 里的 key 根本带不过去动态数据源切换依赖 ThreadLocal 传递 keyThreadLocal 天然是线程私有的。主线程设置完 key再丢到线程池或者CompletableFuture里去执行子线程根本读不到。DynamicDataSourceContextHolder.set(slave); CompletableFuture.runAsync(() - { // 子线程里 get() 是 null orderMapper.selectById(orderId); });这种情况表现出来的问题往往是异步任务里执行查询动态数据源完全没有生效甚至直接走默认数据源。更隐蔽的是线程池复用某个任务里设置了 key 但没清理线程池里的同一个工作线程再跑下一个任务时key 还残留在 ThreadLocal 里导致下一个任务莫名其妙串到了别的库。对于异步任务稳妥的做法是把这个 key 作为参数显式传递给子线程在子线程执行前再设置一次执行完必须清理。直接依赖 ThreadLocal 的隐式传递除非你引入专门支持线程传递的工具包否则很容易踩坑。2.4 内部调用绕过代理DS 注解像没写一样Spring 的 AOP 切面是靠代理对象生效的但同一个类内部的this调用不会经过代理。这个知识点很多人知道但写业务代码的时候还是容易犯。Service public class OrderService { public Order query(String orderId) { return this.queryFromSlave(orderId); } DataSourceKey(slave) public Order queryFromSlave(String orderId) { return orderMapper.selectById(orderId); } }当外部调用query时方法体内部执行的是this.queryFromSlave这里不会走 Spring 生成的代理对象切面自然不会执行DataSourceKey(slave)等于没写。解决方式有几种把queryFromSlave放到另一个 Bean 里或者注入自身代理或者用AopContext.currentProxy()。不管用哪种本质都是让被调用的方法也经过代理对象。3. 动态数据源切换失效的排查方法论3.1 第一件事确认 key 什么时候被设置、什么时候被读取遇到切换失效不要先怀疑配置写错了也不要急着重写动态数据源。第一件事是确认 key 的写入和读取时序。最直接的办法是在determineCurrentLookupKey()里加日志Override protected Object determineCurrentLookupKey() { String key DynamicDataSourceContextHolder.get(); log.debug(determineCurrentLookupKey, key{}, thread{}, key, Thread.currentThread().getName()); return key; }再在自定义切面的入口和出口各打印日志。之后查看日志里三个关键时间点自定义切面设置 key 的时间。determineCurrentLookupKey()读到 key 的时间。事务管理器获取连接的时间。如果日志显示 key 在读方法里已经能看到但连接获取发生在 key 设置之前那问题就出在切面顺序或者事务边界上。如果日志直接显示keynull那就是 ThreadLocal 没传进去要查调用链和多线程。3.2 常见现象、根因与排查方向对照我把实际排查中见过的高频现象整理成一个表排查时可以直接对着找现象可能根因优先排查项方法加了 Transactional 后切换就失效事务启动时已提前获取连接拆分开事务方法和切源方法注解切面日志显示 key 已设置但 SQL 仍走主库事务拦截器先于数据源切面执行给切面加 Order(Ordered.HIGHEST_PRECEDENCE)同一个类内部调用注解像没生效this 调用绕过代理对象改成跨 Bean 调用或使用 AopContext.currentProxy()异步任务里读不到 keyThreadLocal 不跨线程子线程里显式设置 key执行完清理第一次切换正常后面请求串库ThreadLocal 没有被 clear线程被复用检查切面 finally 里是否调用了 clear()外层方法有事务内部方法的切换不生效事务传播行为为 REQUIRED内层方法加入了外层事务确认是否真的需要跨数据源事务必要时使用 REQUIRES_NEW 或改换事务边界3.3 用 JUnit 做最小复现把问题圈定在某一层与其在复杂业务里排查不如写一个最小用例手动验证动态数据源路由本身有没有问题。SpringBootTest class DynamicDataSourceSwitchTest { Autowired private DataSource dataSource; Autowired private JdbcTemplate jdbcTemplate; Test void shouldSwitchToSlaveWhenKeySet() { DynamicDataSourceContextHolder.set(slave); try { String database jdbcTemplate.queryForObject(select database(), String.class); System.out.println(当前库: database); } finally { DynamicDataSourceContextHolder.clear(); } } }这里有两个细节要注意测试类或者测试方法上不要加Transactional否则测试框架会在测试前就开启事务导致手动设置 key 时连接已经被占住。另外最好确认jdbcTemplate注入的是动态数据源而不是某个固定的物理数据源。如果手动设置 key 后能查到从库说明路由实现没问题问题就在业务调用链路的时序和切面上。如果手动设置 key 也查不到从库再回头检查setTargetDataSources的 Map 配置以及 key 字符串是否匹配。3.4 检查事务传播行为对切换的干扰Spring 默认的事务传播行为是REQUIRED。这意味着当一个已经在事务中的 Service 调用另一个需要切换数据源的 Service 时内层 Service 不会开启新事务而是直接加入外层事务共用同一个连接。连接一旦共用内层方法再怎么切换 key也切不动。public void outer() { // 外层已经开启事务 orderService.queryFromSlave(); }这个场景和“事务先于切源运行”很像但要区分的是有时候内层方法确实设置了 key切面也确实执行了但连接已经绑定在外层事务上所有设置都无效。解决办法要么调整事务边界让切换数据源的方法不要落在已有事务里要么明确使用REQUIRES_NEW让它独立成一个新事务。注意REQUIRES_NEW会暂停外层事务、获取新连接但代价是新连接会占用更久并发高时要小心连接池被打满。4. 一套能抗住生产环境的动态数据源写法4.1 完整实现骨架注解 切面 路由数据源先给出一套我验证过比较稳的写法。首先是注解Target({ElementType.METHOD, ElementType.TYPE}) Retention(RetentionPolicy.RUNTIME) public interface DataSourceKey { String value(); }然后是切面核心是Order加上 finally 清理Aspect Component Order(Ordered.HIGHEST_PRECEDENCE) public class DataSourceKeyAspect { Around(annotation(dataSourceKey)) public Object around(ProceedingJoinPoint joinPoint, DataSourceKey dataSourceKey) throws Throwable { DynamicDataSourceContextHolder.set(dataSourceKey.value()); try { return joinPoint.proceed(); } finally { DynamicDataSourceContextHolder.clear(); } } }路由数据源继承AbstractRoutingDataSourcepublic class DynamicDataSource extends AbstractRoutingDataSource { Override protected Object determineCurrentLookupKey() { return DynamicDataSourceContextHolder.get(); } }配置时把物理数据源放进 targetDataSourcesBean Primary public DataSource dynamicDataSource( DataSource masterDataSource, DataSource slaveDataSource) { DynamicDataSource dynamicDataSource new DynamicDataSource(); MapObject, Object dataSourceMap new HashMap(); dataSourceMap.put(master, masterDataSource); dataSourceMap.put(slave, slaveDataSource); dynamicDataSource.setTargetDataSources(dataSourceMap); dynamicDataSource.setDefaultTargetDataSource(masterDataSource); return dynamicDataSource; }这套骨架本身不复杂复杂的是怎么用。我的建议是不要到处给 DAO 加注解切源动作只放在 Service 入口方法上让所有底层 Mapper 都在这个入口内的同一个调用链上执行。4.2 两个设计约定切源与事务分开入口切源第一切源和事务要分开。不要习惯性地在一个方法上同时写Transactional和DataSourceKey。如果确实需要确保你的切面优先级够高、且没有外层事务提前绑定了连接。最稳妥的设计是所有需要切源的方法在进入事务方法前设置 key事务方法内部不要再去改 key。第二切源只放在 Service 入口。放在 DAO 层或者 Mapper 层切源最大的问题是调用时机太靠后很多上层 Service 已经开启了事务连接早就绑定了。放在 Service 入口可以让动态数据源切面尽早执行也方便统一管理 key 的清理。如果项目里同时存在多个 Service要格外注意它们之间的事务传播。A Service 调用 B ServiceA 已经开了事务B 的方法就算切了源也大概率失效。遇到这种场景我会先把调用链拆开要么不让 A 开事务要么干脆把 B 的切源方法改成独立入口而不是嵌在一个不清不楚的调用链路里。4.3 ThreadLocal 的清理一次忘清就是事故ThreadLocal 的清理这个问题值得单独拿出来强调。动态数据源切换里set key 之后不在 finally 里清理等于埋雷。Tomcat 这类 Web 容器默认使用线程池处理请求一次请求结束后线程并不会销毁而是继续服务下一个请求。如果这一次请求里设置了slave但没清理下一个请求复用到同一个线程DynamicDataSourceContextHolder.get()返回的还是slave于是一个完全不相关的请求就莫名其妙走了从库。这种事故很隐蔽因为不是每次都必现只有线程复用到你那个残留 key 的时候才出现。所以在切面里必须这样写try { return joinPoint.proceed(); } finally { DynamicDataSourceContextHolder.clear(); }不只是切面任何手动调用DynamicDataSourceContextHolder.set()的地方都要保证在 finally 里执行clear()。我见过有人把 clear 写在切面里但某个异步方法里手动 set 了 key 又没经过切面导致线程池里的 key 一路残留。这个问题排查起来非常费劲最好从开始就养成“set 和 clear 配对出现”的习惯。4.4 多线程场景下的补充方案多线程传递 key可以用现成的TransmittableThreadLocal或者自己在任务执行前显式传参。我实际用得比较多的还是显式传参因为逻辑清晰排查方便public void asyncQueryFromSlave(String orderId) { String dataSourceKey slave; taskExecutor.execute(() - { DynamicDataSourceContextHolder.set(dataSourceKey); try { orderMapper.selectById(orderId); } finally { DynamicDataSourceContextHolder.clear(); } }); }注意线程池里的线程也会被复用所以子线程里同样必须清理。如果用了TransmittableThreadLocal配套设施也得跟上不是引入一个类就万事大吉。多线程场景的本质是每个线程都要有属于自己的、明确的生命周期key 从这个线程的入口设置从这个线程的出口清理。5. 写在最后的实战体会排查动态数据源切换失效绕来绕去最后都逃不开一个思维模型切换不是状态而是一个时序事件。key 只是开关真正决定结果的是“连接在哪一刻被获取”。所以我个人现在遇到切换失效第一反应不是去翻配置而是先问三个问题这个请求是从哪个线程进来的当前线程有没有已经绑定好的连接set(key)和getConnection()到底谁先执行了顺着这三个问题往下查基本能在很短时间内把根因圈出来而不是在配置文件里来回改。另外还有一点想提醒不要为了“让切换生效”就随便在每个方法上加REQUIRES_NEW。频繁暂停事务、新建连接连接池的压力会成倍增加高并发场景下可能从“切换失效”变成“拿不到连接”。动态数据源本身是数据库资源路由的问题不是事务并发问题解决它优先靠边界和顺序设计而不是靠砸并发能力硬顶。动态数据源切换失效这个话题看起来小背后牵出的全是 Spring 连接管理和 AOP 顺序的细节。把这些底层逻辑吃透后面不管遇到主从分离、多租户隔离还是读写路由都能多一分底气。 
长河君 · 2026/10/13 5:24:10 · 阅读 1.2k Spring动态数据源切换失效：原理、排查与稳定方案
做 Java 后端的同学十有八九都会遇到“动态数据源切换失效”这种怪事。代码里明明把数据源 key 设置成了从库执行查询后一打日志走的还是主库或者第一次正常第二次直接串库还有一种更隐蔽的同一个方法里前几行查询走从库加了一个事务注解之后整段逻辑全跑回主库。这类问题在 Spring 项目里太典型了表现形式千奇百怪但追到根子上基本都是同一个矛盾Spring 的数据源切换是一个基于调用链的行为而连接Connection却是按事务边界缓存和复用的。这篇文章结合我实际排查过的几个案例把 Spring 动态数据源切换失效的底层原理、典型场景、定位方法以及一套稳定写法完整拆一遍适合用过AbstractRoutingDataSource但一直被切换问题困扰的同学。1. 动态数据源切换失效先把底层原理说透1.1 动态数据源是怎么做到按需切换的Spring 里做动态数据源绝大多数项目都会选择AbstractRoutingDataSource。它内部维护了一个MapObject, Object形式的targetDataSources每次调用getConnection()时都会先执行determineCurrentLookupKey()用返回的 key 去这个 Map 里找对应的物理 DataSource。常见的实现大概是这个样子public class DynamicDataSource extends AbstractRoutingDataSource { Override protected Object determineCurrentLookupKey() { return DynamicDataSourceContextHolder.get(); } }而DynamicDataSourceContextHolder本质上就是一个 ThreadLocalpublic class DynamicDataSourceContextHolder { private static final ThreadLocalString CONTEXT new ThreadLocal(); public static void set(String key) { CONTEXT.set(key); } public static String get() { return CONTEXT.get(); } public static void clear() { CONTEXT.remove(); } }这个设计看起来非常优雅DataSource.getConnection()是任何一次数据库操作的必经之路只要 key 在调用链路上被正确设置连接自然就从目标数据源拿。问题是很多人忽略了AbstractRoutingDataSource只在 getConnection 的时候才去读 key而 Spring 里触发getConnection()的时机往往不在你的业务代码里而是在事务管理器里。1.2 连接生命周期切换的不是数据源而是“下一次连接”Spring 的事务管理模型是同一个事务内只在一个物理连接上工作。事务开启后所有 DAO 操作都复用绑定在当前线程上的那个 Connection这个绑定关系由TransactionSynchronizationManager维护。关键点在于声明式事务开启的时候Spring 并不会等到你第一个 Mapper 方法执行才去拿连接。很多场景下事务管理器在执行目标方法之前就已经通过DataSourceUtils.getConnection(dataSource)把连接拿到手了。一旦连接被拿到并且被绑定到当前线程后面再设置动态数据源 key都已经太晚了。已经拿出来的连接不会因为你改了 key 就换一把它只会继续在当前事务里被复用。可以类比成电梯你在进入电梯前选楼层楼层才有效。启动事务就像人已经进了电梯这时候不管按多少次别的楼层按钮电梯都不会换另一台它只会把你送到当前这台电梯里已经选定的楼层。动态数据源切换也一样决定结果的是set(key) 和 getConnection() 谁先谁后。1.3 为什么注解执行了、key 也对了还是没切换成功很多排查过程卡在这里明明在切面里打了日志key 确实被设置成slave了为什么后面执行的 SQL 还是走主库原因很简单key 设置对了不代表连接是在设置之后才获取的。如果连接是在切面设置 key 之前就被事务管理器拿走了那后续所有 SQL 都只会看到那个已经被绑定的连接。更准确地说AbstractRoutingDataSource.determineCurrentLookupKey()只会影响“下一次获取连接”的时机它左右不了“已经存在的连接”。所以判断一个动态数据源切换到底有没有生效不能只看 key 有没有设置进去而要看完整的时序key 的设置必须发生在连接获取之前并且连接获取必须发生在同一个线程里。这个结论是后面所有定位工作的总原则。2. 四个最容易让动态数据源切换失效的场景2.1 事务先于切源运行key 等于是摆在了终点线后面最典型的一种写法就是这样Transactional(readOnly true) public Order queryOrder(String orderId) { DynamicDataSourceContextHolder.set(slave); return orderMapper.selectById(orderId); }看起来没什么问题方法一开始设置了数据源 key然后执行查询。但问题是Transactional在方法进入时就已经启动了事务而事务启动的瞬间事务管理器可能就已经把连接拿到了。等到方法体里执行DynamicDataSourceContextHolder.set(slave)时连接早就绑定在当前线程上了这个 key 只是“白设置”了。这种场景在读写分离项目里极其常见。很多人一开始不用事务时切换一切正常后来因为业务需要加了个Transactional动态数据源立刻失效。原因就是连接获取的时机被事务提前了。正确的思路是把切源和事务拉开先设置 key再进入事务边界。最推荐的方式是拆成两个方法把设置 key 的入口放在不带事务的外层方法public Order queryOrder(String orderId) { DynamicDataSourceContextHolder.set(slave); try { return queryOrderInTx(orderId); } finally { DynamicDataSourceContextHolder.clear(); } } Transactional(readOnly true) public Order queryOrderInTx(String orderId) { return orderMapper.selectById(orderId); }不过这里要注意如果这两个方法在同一个类里外层方法调用内层方法时是this直接调用Transactional会被代理机制绕过内层方法的事务不生效所以最好把queryOrderInTx放到另一个 Spring Bean 里或者使用AopContext.currentProxy()。2.2 切面顺序不对动态数据源切面被事务拦截器抢了先注解方式的动态数据源切换本质上是 AOP。Spring 容器里同时存在事务拦截器和自定义数据源切面时它们的执行顺序是影响切换结果的另一个关键变量。如果自定义数据源切面的执行顺序在事务拦截器的后面事务拦截器先把连接拿了数据源切面再设置 key就晚了。所以动态数据源切面必须明确地指定一个高优先级Aspect Component Order(Ordered.HIGHEST_PRECEDENCE) public class DynamicDataSourceAspect { Around(annotation(dataSourceKey)) public Object switchDataSource(ProceedingJoinPoint joinPoint, DataSourceKey dataSourceKey) throws Throwable { DynamicDataSourceContextHolder.set(dataSourceKey.value()); try { return joinPoint.proceed(); } finally { DynamicDataSourceContextHolder.clear(); } } }Order(Ordered.HIGHEST_PRECEDENCE)保证这个切面比 Spring 默认的事务拦截器先执行。如果项目里还有别的 AOP比如缓存、日志、权限校验也要注意顺序。数据源切换不是越早越好但必须保证早于任何可能触发getConnection()的拦截器。2.3 多线程和异步任务ThreadLocal 里的 key 根本带不过去动态数据源切换依赖 ThreadLocal 传递 keyThreadLocal 天然是线程私有的。主线程设置完 key再丢到线程池或者CompletableFuture里去执行子线程根本读不到。DynamicDataSourceContextHolder.set(slave); CompletableFuture.runAsync(() - { // 子线程里 get() 是 null orderMapper.selectById(orderId); });这种情况表现出来的问题往往是异步任务里执行查询动态数据源完全没有生效甚至直接走默认数据源。更隐蔽的是线程池复用某个任务里设置了 key 但没清理线程池里的同一个工作线程再跑下一个任务时key 还残留在 ThreadLocal 里导致下一个任务莫名其妙串到了别的库。对于异步任务稳妥的做法是把这个 key 作为参数显式传递给子线程在子线程执行前再设置一次执行完必须清理。直接依赖 ThreadLocal 的隐式传递除非你引入专门支持线程传递的工具包否则很容易踩坑。2.4 内部调用绕过代理DS 注解像没写一样Spring 的 AOP 切面是靠代理对象生效的但同一个类内部的this调用不会经过代理。这个知识点很多人知道但写业务代码的时候还是容易犯。Service public class OrderService { public Order query(String orderId) { return this.queryFromSlave(orderId); } DataSourceKey(slave) public Order queryFromSlave(String orderId) { return orderMapper.selectById(orderId); } }当外部调用query时方法体内部执行的是this.queryFromSlave这里不会走 Spring 生成的代理对象切面自然不会执行DataSourceKey(slave)等于没写。解决方式有几种把queryFromSlave放到另一个 Bean 里或者注入自身代理或者用AopContext.currentProxy()。不管用哪种本质都是让被调用的方法也经过代理对象。3. 动态数据源切换失效的排查方法论3.1 第一件事确认 key 什么时候被设置、什么时候被读取遇到切换失效不要先怀疑配置写错了也不要急着重写动态数据源。第一件事是确认 key 的写入和读取时序。最直接的办法是在determineCurrentLookupKey()里加日志Override protected Object determineCurrentLookupKey() { String key DynamicDataSourceContextHolder.get(); log.debug(determineCurrentLookupKey, key{}, thread{}, key, Thread.currentThread().getName()); return key; }再在自定义切面的入口和出口各打印日志。之后查看日志里三个关键时间点自定义切面设置 key 的时间。determineCurrentLookupKey()读到 key 的时间。事务管理器获取连接的时间。如果日志显示 key 在读方法里已经能看到但连接获取发生在 key 设置之前那问题就出在切面顺序或者事务边界上。如果日志直接显示keynull那就是 ThreadLocal 没传进去要查调用链和多线程。3.2 常见现象、根因与排查方向对照我把实际排查中见过的高频现象整理成一个表排查时可以直接对着找现象可能根因优先排查项方法加了 Transactional 后切换就失效事务启动时已提前获取连接拆分开事务方法和切源方法注解切面日志显示 key 已设置但 SQL 仍走主库事务拦截器先于数据源切面执行给切面加 Order(Ordered.HIGHEST_PRECEDENCE)同一个类内部调用注解像没生效this 调用绕过代理对象改成跨 Bean 调用或使用 AopContext.currentProxy()异步任务里读不到 keyThreadLocal 不跨线程子线程里显式设置 key执行完清理第一次切换正常后面请求串库ThreadLocal 没有被 clear线程被复用检查切面 finally 里是否调用了 clear()外层方法有事务内部方法的切换不生效事务传播行为为 REQUIRED内层方法加入了外层事务确认是否真的需要跨数据源事务必要时使用 REQUIRES_NEW 或改换事务边界3.3 用 JUnit 做最小复现把问题圈定在某一层与其在复杂业务里排查不如写一个最小用例手动验证动态数据源路由本身有没有问题。SpringBootTest class DynamicDataSourceSwitchTest { Autowired private DataSource dataSource; Autowired private JdbcTemplate jdbcTemplate; Test void shouldSwitchToSlaveWhenKeySet() { DynamicDataSourceContextHolder.set(slave); try { String database jdbcTemplate.queryForObject(select database(), String.class); System.out.println(当前库: database); } finally { DynamicDataSourceContextHolder.clear(); } } }这里有两个细节要注意测试类或者测试方法上不要加Transactional否则测试框架会在测试前就开启事务导致手动设置 key 时连接已经被占住。另外最好确认jdbcTemplate注入的是动态数据源而不是某个固定的物理数据源。如果手动设置 key 后能查到从库说明路由实现没问题问题就在业务调用链路的时序和切面上。如果手动设置 key 也查不到从库再回头检查setTargetDataSources的 Map 配置以及 key 字符串是否匹配。3.4 检查事务传播行为对切换的干扰Spring 默认的事务传播行为是REQUIRED。这意味着当一个已经在事务中的 Service 调用另一个需要切换数据源的 Service 时内层 Service 不会开启新事务而是直接加入外层事务共用同一个连接。连接一旦共用内层方法再怎么切换 key也切不动。public void outer() { // 外层已经开启事务 orderService.queryFromSlave(); }这个场景和“事务先于切源运行”很像但要区分的是有时候内层方法确实设置了 key切面也确实执行了但连接已经绑定在外层事务上所有设置都无效。解决办法要么调整事务边界让切换数据源的方法不要落在已有事务里要么明确使用REQUIRES_NEW让它独立成一个新事务。注意REQUIRES_NEW会暂停外层事务、获取新连接但代价是新连接会占用更久并发高时要小心连接池被打满。4. 一套能抗住生产环境的动态数据源写法4.1 完整实现骨架注解 切面 路由数据源先给出一套我验证过比较稳的写法。首先是注解Target({ElementType.METHOD, ElementType.TYPE}) Retention(RetentionPolicy.RUNTIME) public interface DataSourceKey { String value(); }然后是切面核心是Order加上 finally 清理Aspect Component Order(Ordered.HIGHEST_PRECEDENCE) public class DataSourceKeyAspect { Around(annotation(dataSourceKey)) public Object around(ProceedingJoinPoint joinPoint, DataSourceKey dataSourceKey) throws Throwable { DynamicDataSourceContextHolder.set(dataSourceKey.value()); try { return joinPoint.proceed(); } finally { DynamicDataSourceContextHolder.clear(); } } }路由数据源继承AbstractRoutingDataSourcepublic class DynamicDataSource extends AbstractRoutingDataSource { Override protected Object determineCurrentLookupKey() { return DynamicDataSourceContextHolder.get(); } }配置时把物理数据源放进 targetDataSourcesBean Primary public DataSource dynamicDataSource( DataSource masterDataSource, DataSource slaveDataSource) { DynamicDataSource dynamicDataSource new DynamicDataSource(); MapObject, Object dataSourceMap new HashMap(); dataSourceMap.put(master, masterDataSource); dataSourceMap.put(slave, slaveDataSource); dynamicDataSource.setTargetDataSources(dataSourceMap); dynamicDataSource.setDefaultTargetDataSource(masterDataSource); return dynamicDataSource; }这套骨架本身不复杂复杂的是怎么用。我的建议是不要到处给 DAO 加注解切源动作只放在 Service 入口方法上让所有底层 Mapper 都在这个入口内的同一个调用链上执行。4.2 两个设计约定切源与事务分开入口切源第一切源和事务要分开。不要习惯性地在一个方法上同时写Transactional和DataSourceKey。如果确实需要确保你的切面优先级够高、且没有外层事务提前绑定了连接。最稳妥的设计是所有需要切源的方法在进入事务方法前设置 key事务方法内部不要再去改 key。第二切源只放在 Service 入口。放在 DAO 层或者 Mapper 层切源最大的问题是调用时机太靠后很多上层 Service 已经开启了事务连接早就绑定了。放在 Service 入口可以让动态数据源切面尽早执行也方便统一管理 key 的清理。如果项目里同时存在多个 Service要格外注意它们之间的事务传播。A Service 调用 B ServiceA 已经开了事务B 的方法就算切了源也大概率失效。遇到这种场景我会先把调用链拆开要么不让 A 开事务要么干脆把 B 的切源方法改成独立入口而不是嵌在一个不清不楚的调用链路里。4.3 ThreadLocal 的清理一次忘清就是事故ThreadLocal 的清理这个问题值得单独拿出来强调。动态数据源切换里set key 之后不在 finally 里清理等于埋雷。Tomcat 这类 Web 容器默认使用线程池处理请求一次请求结束后线程并不会销毁而是继续服务下一个请求。如果这一次请求里设置了slave但没清理下一个请求复用到同一个线程DynamicDataSourceContextHolder.get()返回的还是slave于是一个完全不相关的请求就莫名其妙走了从库。这种事故很隐蔽因为不是每次都必现只有线程复用到你那个残留 key 的时候才出现。所以在切面里必须这样写try { return joinPoint.proceed(); } finally { DynamicDataSourceContextHolder.clear(); }不只是切面任何手动调用DynamicDataSourceContextHolder.set()的地方都要保证在 finally 里执行clear()。我见过有人把 clear 写在切面里但某个异步方法里手动 set 了 key 又没经过切面导致线程池里的 key 一路残留。这个问题排查起来非常费劲最好从开始就养成“set 和 clear 配对出现”的习惯。4.4 多线程场景下的补充方案多线程传递 key可以用现成的TransmittableThreadLocal或者自己在任务执行前显式传参。我实际用得比较多的还是显式传参因为逻辑清晰排查方便public void asyncQueryFromSlave(String orderId) { String dataSourceKey slave; taskExecutor.execute(() - { DynamicDataSourceContextHolder.set(dataSourceKey); try { orderMapper.selectById(orderId); } finally { DynamicDataSourceContextHolder.clear(); } }); }注意线程池里的线程也会被复用所以子线程里同样必须清理。如果用了TransmittableThreadLocal配套设施也得跟上不是引入一个类就万事大吉。多线程场景的本质是每个线程都要有属于自己的、明确的生命周期key 从这个线程的入口设置从这个线程的出口清理。5. 写在最后的实战体会排查动态数据源切换失效绕来绕去最后都逃不开一个思维模型切换不是状态而是一个时序事件。key 只是开关真正决定结果的是“连接在哪一刻被获取”。所以我个人现在遇到切换失效第一反应不是去翻配置而是先问三个问题这个请求是从哪个线程进来的当前线程有没有已经绑定好的连接set(key)和getConnection()到底谁先执行了顺着这三个问题往下查基本能在很短时间内把根因圈出来而不是在配置文件里来回改。另外还有一点想提醒不要为了“让切换生效”就随便在每个方法上加REQUIRES_NEW。频繁暂停事务、新建连接连接池的压力会成倍增加高并发场景下可能从“切换失效”变成“拿不到连接”。动态数据源本身是数据库资源路由的问题不是事务并发问题解决它优先靠边界和顺序设计而不是靠砸并发能力硬顶。动态数据源切换失效这个话题看起来小背后牵出的全是 Spring 连接管理和 AOP 顺序的细节。把这些底层逻辑吃透后面不管遇到主从分离、多租户隔离还是读写路由都能多一分底气。