1. 从一次数据库迁移引发的思考为什么需要动态数据源去年参与一个多租户SaaS系统的重构遇到了一个很典型的问题系统需要同时连接三个物理库——主业务库、报表库、还有一个历史归档库。最开始的方案是每个DAO层方法都显式传入数据源标识代码里到处都是if-else判断该用哪个库维护起来简直是噩梦。后来改用Spring的AbstractRoutingDataSource配合ThreadLocal才算真正把这个问题优雅地解决了。动态数据源切换这个需求在实际项目里出现的频率远比想象中高。读写分离是最常见的场景——写操作走主库读操作走从库通过ThreadLocal在方法调用链中传递当前应该使用的数据源标识AOP切面在方法执行前设置、执行后清理。多租户系统里每个租户可能对应独立的数据库实例同样需要在请求入口处根据租户ID绑定数据源。还有分库分表场景根据分片键路由到不同的物理库本质上也是动态数据源切换的一种变体。ThreadLocal之所以成为实现这个功能的核心工具原因在于它的线程隔离特性。一个HTTP请求从进入Controller到最终返回响应通常由同一个线程处理不考虑异步场景在这个线程的生命周期内通过ThreadLocal存储的数据源标识可以被DAO层的任意代码读取到而不需要一层层通过方法参数传递。这就像给每个线程发了一个专属的储物柜线程走到哪里都能打开自己的柜子取出需要的东西互不干扰。但这里有个容易被忽视的细节ThreadLocal的值必须在请求结束后清理否则在线程池场景下会造成内存泄漏和数据污染。我见过一个线上事故就是因为忘记在finally块中调用remove()导致下一个请求复用了上一个请求的数据源标识把报表查询打到了主库上差点把主库拖垮。这个坑后面会详细展开。这篇文章会从原理到实战完整拆解基于ThreadLocal实现动态数据源切换的每一个环节。不管你是正在做读写分离、多租户改造还是单纯想理解ThreadLocal在框架层面的经典应用都能从中找到可以直接复用的代码和踩坑经验。2. ThreadLocal与AbstractRoutingDataSource的协作机制2.1 ThreadLocal的线程隔离本质要理解动态数据源切换得先把ThreadLocal的底层结构搞清楚。每个Thread对象内部都有一个ThreadLocalMap类型的成员变量这个Map的key是ThreadLocal实例本身准确说是弱引用value就是实际存储的值。当你调用threadLocal.set(value)时实际上是在当前线程的ThreadLocalMap里插入了一条记录调用get()时从当前线程的Map里取出对应的值。这种设计带来的直接效果是线程A设置的值线程B完全看不到。在Web应用中Tomcat的工作线程处理请求时从ThreadLocal中读取数据源标识天然就是线程安全的。不需要加锁不需要同步性能开销极低。但这里有个关键点需要特别注意ThreadLocalMap的Entry对key是弱引用对value是强引用。如果ThreadLocal实例被回收了key变成null但value还挂在Entry上而Entry又被Thread强引用着这就导致value无法被GC回收。在线程池场景下线程生命周期极长这些无法回收的value就会越积越多最终OOM。所以remove()操作不是可选项而是必须项。2.2 AbstractRoutingDataSource的路由逻辑Spring提供的AbstractRoutingDataSource是动态数据源切换的基石。它本身实现了DataSource接口内部维护了一个MapObject, DataSource作为目标数据源集合以及一个默认数据源。当你调用getConnection()时它并不是直接返回某个物理连接而是先调用抽象方法determineCurrentLookupKey()获取一个key然后用这个key去Map里找到对应的数据源最后委托给那个数据源去获取连接。整个流程可以拆解为三步应用层通过ThreadLocal设置当前线程的数据源标识AbstractRoutingDataSource.determineCurrentLookupKey()从ThreadLocal中读取这个标识根据标识从目标数据源Map中选出对应的DataSource获取数据库连接这个设计的美妙之处在于它把选择哪个数据源这个决策逻辑抽象成了一个钩子方法你可以自由决定key从哪里来——可以是从ThreadLocal读也可以从配置中心读甚至可以根据当前时间动态计算。而ThreadLocal方案之所以最常用是因为它和请求的生命周期天然对齐。2.3 一次请求中数据源标识的完整流转假设一个典型的读写分离场景用户发起一个查询请求整个链路的流转过程是这样的请求到达Controller层此时还没有确定用哪个数据源。进入Service层某个方法上标注了DataSource(slave)注解。AOP切面拦截到这个注解在方法执行前调用DataSourceContextHolder.set(slave)把标识写入ThreadLocal。方法内部调用DAO层DAO层通过AbstractRoutingDataSource获取连接时determineCurrentLookupKey()从ThreadLocal读到slave于是返回从库的数据源。方法执行完毕AOP切面的finally块调用DataSourceContextHolder.clear()清理ThreadLocal。如果Service方法内部又调用了另一个标注了DataSource(master)的方法切面会再次设置ThreadLocal为master方法结束后恢复为之前的值。这就涉及到ThreadLocal的嵌套设置问题后面会专门讲如何用栈结构来管理。注意ThreadLocal的set操作是覆盖式的如果嵌套调用中内层方法结束后直接clear外层方法再读取时就会拿到null。正确的做法是保存旧值方法结束后恢复旧值而不是简单清除。3. 手把手搭建可运行的数据源切换Demo3.1 定义数据源上下文持有器先来写最核心的DataSourceContextHolder类。这个类的职责很简单封装ThreadLocal的set、get、clear操作同时支持嵌套场景下的栈式管理。public class DataSourceContextHolder { private static final ThreadLocalDequeString CONTEXT_HOLDER ThreadLocal.withInitial(ArrayDeque::new); public static void push(String dataSourceKey) { CONTEXT_HOLDER.get().push(dataSourceKey); } public static String peek() { return CONTEXT_HOLDER.get().peek(); } public static void poll() { DequeString deque CONTEXT_HOLDER.get(); deque.poll(); if (deque.isEmpty()) { CONTEXT_HOLDER.remove(); } } public static void clear() { CONTEXT_HOLDER.remove(); } }这里用Deque而不是单个String是为了支持嵌套切换。每次push把新数据源压入栈顶peek取栈顶元素作为当前数据源poll弹出栈顶。当栈为空时主动调用remove()清理ThreadLocal避免内存泄漏。为什么用ArrayDeque而不是StackStack是遗留类继承自Vector所有方法都加了synchronized在单线程环境下这是不必要的开销。ArrayDeque性能更好而且Deque接口提供了更完整的栈操作语义。3.2 实现动态数据源路由类接下来继承AbstractRoutingDataSource实现determineCurrentLookupKey()方法public class DynamicDataSource extends AbstractRoutingDataSource { Override protected Object determineCurrentLookupKey() { String key DataSourceContextHolder.peek(); return key ! null ? key : master; } }逻辑很直白从ThreadLocal栈顶取数据源标识如果为空则返回默认的master。这个默认值很重要它保证了在没有显式指定数据源时系统仍然能正常工作。3.3 配置多数据源与路由规则在配置类中定义多个物理数据源并注册到DynamicDataSource中Configuration public class DataSourceConfig { Bean(master) ConfigurationProperties(prefix spring.datasource.master) public DataSource masterDataSource() { return DataSourceBuilder.create().build(); } Bean(slave) ConfigurationProperties(prefix spring.datasource.slave) public DataSource slaveDataSource() { return DataSourceBuilder.create().build(); } Bean Primary public DataSource dynamicDataSource( Qualifier(master) DataSource master, Qualifier(slave) DataSource slave) { MapObject, Object targetDataSources new HashMap(); targetDataSources.put(master, master); targetDataSources.put(slave, slave); DynamicDataSource dynamicDataSource new DynamicDataSource(); dynamicDataSource.setTargetDataSources(targetDataSources); dynamicDataSource.setDefaultTargetDataSource(master); return dynamicDataSource; } }配置文件里对应写两组数据库连接参数分别以spring.datasource.master和spring.datasource.slave为前缀。这里有个细节Primary必须加在dynamicDataSource上否则Spring在自动装配时会因为存在多个DataSource类型的Bean而报错。3.4 自定义注解与AOP切面为了让数据源切换对业务代码透明定义一个DataSource注解Target({ElementType.METHOD, ElementType.TYPE}) Retention(RetentionPolicy.RUNTIME) Documented public interface DataSource { String value() default master; }然后写AOP切面拦截标注了该注解的方法Aspect Component Order(Ordered.HIGHEST_PRECEDENCE) public class DataSourceAspect { Around(annotation(dataSource)) public Object around(ProceedingJoinPoint point, DataSource dataSource) throws Throwable { String key dataSource.value(); DataSourceContextHolder.push(key); try { return point.proceed(); } finally { DataSourceContextHolder.poll(); } } }Order(Ordered.HIGHEST_PRECEDENCE)确保这个切面在所有其他切面之前执行避免事务切面先获取了连接再切换数据源导致失效。这个顺序问题是个大坑后面会详细说。3.5 验证切换是否生效写一个简单的测试Service来验证Service public class UserService { Autowired private JdbcTemplate jdbcTemplate; DataSource(master) public void insertUser(String name) { jdbcTemplate.update(INSERT INTO user(name) VALUES(?), name); } DataSource(slave) public ListMapString, Object queryUsers() { return jdbcTemplate.queryForList(SELECT * FROM user); } }启动应用后调用这两个方法通过日志或数据库监控确认写操作走了主库、读操作走了从库。如果两个库的数据不一致比如主从延迟查询结果能直观反映出切换是否生效。4. 那些只有踩过才知道的坑4.1 事务与数据源切换的顺序陷阱这是最容易出问题的地方。Spring的Transactional注解通过AOP实现在方法执行前就通过DataSourceTransactionManager获取了数据库连接并绑定到ThreadLocal中。如果数据源切换的切面在事务切面之后执行那么事务已经用默认数据源开启了连接后面的切换根本不会生效。解决方案是确保数据源切面的Order值小于事务切面的Order值。Spring事务切面的默认Order是Ordered.LOWEST_PRECEDENCE所以只要给数据源切面设置一个较小的值比如Ordered.HIGHEST_PRECEDENCE就能保证它先执行。但即使顺序对了还有一个更隐蔽的问题在同一个事务中切换数据源是无效的。因为事务一旦开启连接就已经确定了后续的切换只是改变了ThreadLocal的值但实际使用的连接不会变。如果业务确实需要在一个事务中操作多个库那只能考虑分布式事务方案或者把操作拆分成多个独立事务。4.2 异步线程中ThreadLocal的丢失ThreadLocal的值不会自动传递到子线程。如果Service方法中开启了异步任务异步线程里读取ThreadLocal会得到null导致数据源切换失效。这个问题在使用了线程池的场景下尤其常见。InheritableThreadLocal可以解决父子线程传递的问题但在线程池场景下依然无效——因为线程池中的线程是复用的创建时机不确定InheritableThreadLocal只在子线程创建时拷贝一次父线程的值。更可靠的方案是使用TransmittableThreadLocal阿里开源的TTL库它通过装饰Runnable/Callable在任务提交时捕获当前线程的ThreadLocal值在任务执行时恢复到执行线程中。如果不想引入额外依赖也可以在提交异步任务时手动传递数据源标识在异步任务内部重新set。虽然麻烦一点但胜在可控。4.3 连接池层面的数据源隔离多个数据源意味着多个连接池。如果每个数据源都配置了最大连接数总连接数就是各数据源之和。在数据库连接数有限的情况下需要合理分配每个池的大小。我见过一个配置主库和从库各配了50个最大连接结果数据库最大连接数只有100稍微一压测就报too many connections。另外从库通常承担读流量连接数可以适当多配一些主库主要承担写流量连接数可以少一些。具体数值要根据实际压测结果调整没有一个放之四海而皆准的公式。4.4 事务同步器与数据源切换的冲突Spring的TransactionSynchronizationManager在事务开启时会把连接资源绑定到ThreadLocal中。当数据源切换后如果事务同步器还持有旧数据源的连接资源就会出现切换了数据源但事务还在用旧连接的诡异现象。排查这类问题时可以在determineCurrentLookupKey()方法中打印当前线程名和ThreadLocal中的值同时在获取连接的地方打印实际使用的数据源标识对比两者是否一致。如果不一致基本可以确定是事务同步器的问题。5. 从单库到多租户动态数据源的扩展思路5.1 多租户场景下的数据源路由多租户系统的数据源切换逻辑和读写分离类似但key的来源不同。读写分离的key是固定的master或slave而多租户的key是租户ID需要在请求入口处从请求头、Token或域名中解析出来。一种常见的做法是在过滤器中解析租户ID然后调用DataSourceContextHolder.push(tenantId)。但这里有个问题租户数量可能很多不可能为每个租户都预先配置一个数据源。这时候需要换一种思路——不是为每个租户配置独立数据源而是根据租户ID计算出分片多个租户共享同一个物理库。AbstractRoutingDataSource的targetDataSources是一个Mapkey可以是任意对象。你可以把租户ID到数据源key的映射关系存在这个Map里也可以重写determineCurrentLookupKey()方法在里面根据租户ID动态计算出数据源key。5.2 动态增删数据源的运行时方案标准的AbstractRoutingDataSource在初始化后targetDataSources是不可变的。如果需要在运行时动态添加数据源比如新租户开通时自动创建数据库需要做一些扩展。思路是继承AbstractRoutingDataSource暴露一个addDataSource方法内部维护一个可变的Map并在添加后调用afterPropertiesSet()重新初始化。但要注意线程安全问题添加数据源时需要用ConcurrentHashMap或加锁保护。另一种更彻底的方案是不使用AbstractRoutingDataSource自己实现一个DataSource在getConnection()方法中根据ThreadLocal中的key从动态Map中查找数据源。这样灵活性更高但需要自己处理连接池的管理和生命周期。5.3 数据源健康检查与故障转移多个数据源意味着多个故障点。如果从库宕机了读请求应该自动降级到主库而不是直接报错。可以在determineCurrentLookupKey()中增加健康检查逻辑如果目标数据源不可用返回默认数据源。健康检查的实现方式有多种可以用连接池提供的检测机制也可以定时执行SELECT 1探活。关键是要把检查结果缓存起来避免每次获取连接都去探测那样性能开销太大。通常设置一个几十秒的缓存过期时间就足够了。5.4 监控与可观测性建设动态数据源切换的监控至少需要覆盖三个维度每个数据源的连接数使用情况、切换操作的频率和耗时、切换失败或降级的次数。这些指标可以通过Micrometer等工具暴露给监控系统。日志方面建议在determineCurrentLookupKey()中打debug日志记录线程名、当前数据源key和调用栈。线上出问题时这些日志是排查的第一手资料。但要注意日志量高并发场景下全量打印会拖慢性能可以加采样率控制。6. 几个值得关注的实现细节6.1 默认数据源的选择策略setDefaultTargetDataSource()设置的默认数据源在determineCurrentLookupKey()返回null时生效。大多数场景下默认数据源应该设为主库因为写操作对数据一致性要求更高读操作走从库即使出问题影响也相对小。但如果是读多写少的系统把默认数据源设为从库也未尝不可只是需要确保所有写操作都显式标注了DataSource(master)。这个选择没有绝对的对错取决于业务对一致性和性能的权衡。6.2 注解在类级别与方法级别的优先级DataSource注解可以标注在类上也可以标注在方法上。当两者同时存在时方法级别的注解应该优先。实现这个逻辑需要在AOP切面中先检查方法上是否有注解没有再去检查类上是否有。Around(within(com.example.annotation.DataSource) || annotation(com.example.annotation.DataSource)) public Object around(ProceedingJoinPoint point) throws Throwable { MethodSignature signature (MethodSignature) point.getSignature(); Method method signature.getMethod(); DataSource dataSource method.getAnnotation(DataSource.class); if (dataSource null) { dataSource point.getTarget().getClass().getAnnotation(DataSource.class); } // ... }这个细节虽然小但能让注解的使用更加灵活。比如整个Service类都走从库只需要在类上标注一次个别写方法再单独标注主库即可。6.3 与MyBatis插件的配合如果项目使用MyBatis还可以通过拦截器在SQL执行前根据SQL类型自动切换数据源。SELECT语句走从库INSERT、UPDATE、DELETE走主库。这种方式对业务代码完全无侵入但灵活性不如注解方式——比如某些对实时性要求高的查询即使走从库有延迟也必须走主库自动切换就无法满足这种需求。实际项目中注解方式和MyBatis插件方式可以结合使用默认由插件自动路由特殊场景用注解强制指定。这样既减少了手动标注的工作量又保留了精细控制的能力。6.4 单元测试中的数据源Mock测试动态数据源切换逻辑时不需要真的连数据库。可以MockDataSourceContextHolder的行为验证在调用不同方法时ThreadLocal中的值是否符合预期。对于AbstractRoutingDataSource的路由逻辑可以单独写测试类手动设置ThreadLocal的值然后断言determineCurrentLookupKey()的返回值。集成测试则需要真实的多个数据源通常用H2内存数据库模拟主库和从库通过不同的JDBC URL区分。测试完成后记得清理ThreadLocal避免测试用例之间相互影响。6.5 性能开销的实测数据ThreadLocal的set和get操作本质上是对当前线程内部Map的读写没有锁竞争单次操作在纳秒级别。AbstractRoutingDataSource的determineCurrentLookupKey()调用和Map查找也是常数时间复杂度。整体来看动态数据源切换带来的额外开销相对于一次数据库查询毫秒级完全可以忽略不计。真正可能影响性能的是连接池的配置和数据库本身的响应速度而不是切换逻辑本身。所以在这个方案上不需要过度优化把精力放在连接池调优和SQL优化上收益更大。6.6 与Spring Boot自动配置的整合Spring Boot的DataSourceAutoConfiguration默认只配置一个数据源。引入多数据源后需要排除自动配置或者用Primary标记动态数据源让自动配置以它为准。同时JdbcTemplate、MyBatis等组件的自动配置也需要确保注入的是动态数据源而不是某个物理数据源。一个常见的错误是JdbcTemplate自动注入了master数据源导致所有操作都走主库数据源切换完全失效。排查时可以在启动日志中搜索数据源初始化的相关信息确认各组件实际使用的是哪个数据源。6.7 数据源切换的边界条件有几种情况需要特别处理ThreadLocal中没有任何值时应该返回默认数据源数据源key在targetDataSources中不存在时应该抛出明确的异常而不是返回null导致空指针嵌套切换时内层方法结束后必须恢复到外层的值而不是直接清空。这些边界条件在正常流程中很少触发但一旦出问题往往很难排查。建议在determineCurrentLookupKey()中加上防御性判断和清晰的日志输出把问题暴露在早期而不是等到线上事故才发现。6.8 从ThreadLocal到Reactor Context的演进如果项目使用的是Spring WebFlux等响应式框架ThreadLocal就不再适用了因为一个请求可能在不同线程间流转。响应式编程中对应的解决方案是Reactor的Context它能在响应式链中传递上下文信息。虽然实现机制不同但核心思想是一致的在请求入口处绑定数据源标识在数据访问层读取这个标识请求结束后清理。理解ThreadLocal方案的本质有助于在切换技术栈时快速找到对应的替代方案。无论是ThreadLocal、InheritableThreadLocal、TransmittableThreadLocal还是ReactorContext解决的都是同一个问题如何在调用链中隐式传递上下文信息。我在实际项目中的体会是动态数据源切换这个功能代码量不大但细节极多。每一个看似简单的设计决策背后都可能隐藏着事务、线程、连接池层面的连锁反应。把上面这些坑都踩过一遍之后再回头看ThreadLocal和AbstractRoutingDataSource的源码会有一种豁然开朗的感觉——原来Spring早就把扩展点留好了只是需要理解它的运作机制才能用得恰到好处。
1. 从一次数据库迁移引发的思考为什么需要动态数据源去年参与一个多租户SaaS系统的重构遇到了一个很典型的问题系统需要同时连接三个物理库——主业务库、报表库、还有一个历史归档库。最开始的方案是每个DAO层方法都显式传入数据源标识代码里到处都是if-else判断该用哪个库维护起来简直是噩梦。后来改用Spring的AbstractRoutingDataSource配合ThreadLocal才算真正把这个问题优雅地解决了。动态数据源切换这个需求在实际项目里出现的频率远比想象中高。读写分离是最常见的场景——写操作走主库读操作走从库通过ThreadLocal在方法调用链中传递当前应该使用的数据源标识AOP切面在方法执行前设置、执行后清理。多租户系统里每个租户可能对应独立的数据库实例同样需要在请求入口处根据租户ID绑定数据源。还有分库分表场景根据分片键路由到不同的物理库本质上也是动态数据源切换的一种变体。ThreadLocal之所以成为实现这个功能的核心工具原因在于它的线程隔离特性。一个HTTP请求从进入Controller到最终返回响应通常由同一个线程处理不考虑异步场景在这个线程的生命周期内通过ThreadLocal存储的数据源标识可以被DAO层的任意代码读取到而不需要一层层通过方法参数传递。这就像给每个线程发了一个专属的储物柜线程走到哪里都能打开自己的柜子取出需要的东西互不干扰。但这里有个容易被忽视的细节ThreadLocal的值必须在请求结束后清理否则在线程池场景下会造成内存泄漏和数据污染。我见过一个线上事故就是因为忘记在finally块中调用remove()导致下一个请求复用了上一个请求的数据源标识把报表查询打到了主库上差点把主库拖垮。这个坑后面会详细展开。这篇文章会从原理到实战完整拆解基于ThreadLocal实现动态数据源切换的每一个环节。不管你是正在做读写分离、多租户改造还是单纯想理解ThreadLocal在框架层面的经典应用都能从中找到可以直接复用的代码和踩坑经验。2. ThreadLocal与AbstractRoutingDataSource的协作机制2.1 ThreadLocal的线程隔离本质要理解动态数据源切换得先把ThreadLocal的底层结构搞清楚。每个Thread对象内部都有一个ThreadLocalMap类型的成员变量这个Map的key是ThreadLocal实例本身准确说是弱引用value就是实际存储的值。当你调用threadLocal.set(value)时实际上是在当前线程的ThreadLocalMap里插入了一条记录调用get()时从当前线程的Map里取出对应的值。这种设计带来的直接效果是线程A设置的值线程B完全看不到。在Web应用中Tomcat的工作线程处理请求时从ThreadLocal中读取数据源标识天然就是线程安全的。不需要加锁不需要同步性能开销极低。但这里有个关键点需要特别注意ThreadLocalMap的Entry对key是弱引用对value是强引用。如果ThreadLocal实例被回收了key变成null但value还挂在Entry上而Entry又被Thread强引用着这就导致value无法被GC回收。在线程池场景下线程生命周期极长这些无法回收的value就会越积越多最终OOM。所以remove()操作不是可选项而是必须项。2.2 AbstractRoutingDataSource的路由逻辑Spring提供的AbstractRoutingDataSource是动态数据源切换的基石。它本身实现了DataSource接口内部维护了一个MapObject, DataSource作为目标数据源集合以及一个默认数据源。当你调用getConnection()时它并不是直接返回某个物理连接而是先调用抽象方法determineCurrentLookupKey()获取一个key然后用这个key去Map里找到对应的数据源最后委托给那个数据源去获取连接。整个流程可以拆解为三步应用层通过ThreadLocal设置当前线程的数据源标识AbstractRoutingDataSource.determineCurrentLookupKey()从ThreadLocal中读取这个标识根据标识从目标数据源Map中选出对应的DataSource获取数据库连接这个设计的美妙之处在于它把选择哪个数据源这个决策逻辑抽象成了一个钩子方法你可以自由决定key从哪里来——可以是从ThreadLocal读也可以从配置中心读甚至可以根据当前时间动态计算。而ThreadLocal方案之所以最常用是因为它和请求的生命周期天然对齐。2.3 一次请求中数据源标识的完整流转假设一个典型的读写分离场景用户发起一个查询请求整个链路的流转过程是这样的请求到达Controller层此时还没有确定用哪个数据源。进入Service层某个方法上标注了DataSource(slave)注解。AOP切面拦截到这个注解在方法执行前调用DataSourceContextHolder.set(slave)把标识写入ThreadLocal。方法内部调用DAO层DAO层通过AbstractRoutingDataSource获取连接时determineCurrentLookupKey()从ThreadLocal读到slave于是返回从库的数据源。方法执行完毕AOP切面的finally块调用DataSourceContextHolder.clear()清理ThreadLocal。如果Service方法内部又调用了另一个标注了DataSource(master)的方法切面会再次设置ThreadLocal为master方法结束后恢复为之前的值。这就涉及到ThreadLocal的嵌套设置问题后面会专门讲如何用栈结构来管理。注意ThreadLocal的set操作是覆盖式的如果嵌套调用中内层方法结束后直接clear外层方法再读取时就会拿到null。正确的做法是保存旧值方法结束后恢复旧值而不是简单清除。3. 手把手搭建可运行的数据源切换Demo3.1 定义数据源上下文持有器先来写最核心的DataSourceContextHolder类。这个类的职责很简单封装ThreadLocal的set、get、clear操作同时支持嵌套场景下的栈式管理。public class DataSourceContextHolder { private static final ThreadLocalDequeString CONTEXT_HOLDER ThreadLocal.withInitial(ArrayDeque::new); public static void push(String dataSourceKey) { CONTEXT_HOLDER.get().push(dataSourceKey); } public static String peek() { return CONTEXT_HOLDER.get().peek(); } public static void poll() { DequeString deque CONTEXT_HOLDER.get(); deque.poll(); if (deque.isEmpty()) { CONTEXT_HOLDER.remove(); } } public static void clear() { CONTEXT_HOLDER.remove(); } }这里用Deque而不是单个String是为了支持嵌套切换。每次push把新数据源压入栈顶peek取栈顶元素作为当前数据源poll弹出栈顶。当栈为空时主动调用remove()清理ThreadLocal避免内存泄漏。为什么用ArrayDeque而不是StackStack是遗留类继承自Vector所有方法都加了synchronized在单线程环境下这是不必要的开销。ArrayDeque性能更好而且Deque接口提供了更完整的栈操作语义。3.2 实现动态数据源路由类接下来继承AbstractRoutingDataSource实现determineCurrentLookupKey()方法public class DynamicDataSource extends AbstractRoutingDataSource { Override protected Object determineCurrentLookupKey() { String key DataSourceContextHolder.peek(); return key ! null ? key : master; } }逻辑很直白从ThreadLocal栈顶取数据源标识如果为空则返回默认的master。这个默认值很重要它保证了在没有显式指定数据源时系统仍然能正常工作。3.3 配置多数据源与路由规则在配置类中定义多个物理数据源并注册到DynamicDataSource中Configuration public class DataSourceConfig { Bean(master) ConfigurationProperties(prefix spring.datasource.master) public DataSource masterDataSource() { return DataSourceBuilder.create().build(); } Bean(slave) ConfigurationProperties(prefix spring.datasource.slave) public DataSource slaveDataSource() { return DataSourceBuilder.create().build(); } Bean Primary public DataSource dynamicDataSource( Qualifier(master) DataSource master, Qualifier(slave) DataSource slave) { MapObject, Object targetDataSources new HashMap(); targetDataSources.put(master, master); targetDataSources.put(slave, slave); DynamicDataSource dynamicDataSource new DynamicDataSource(); dynamicDataSource.setTargetDataSources(targetDataSources); dynamicDataSource.setDefaultTargetDataSource(master); return dynamicDataSource; } }配置文件里对应写两组数据库连接参数分别以spring.datasource.master和spring.datasource.slave为前缀。这里有个细节Primary必须加在dynamicDataSource上否则Spring在自动装配时会因为存在多个DataSource类型的Bean而报错。3.4 自定义注解与AOP切面为了让数据源切换对业务代码透明定义一个DataSource注解Target({ElementType.METHOD, ElementType.TYPE}) Retention(RetentionPolicy.RUNTIME) Documented public interface DataSource { String value() default master; }然后写AOP切面拦截标注了该注解的方法Aspect Component Order(Ordered.HIGHEST_PRECEDENCE) public class DataSourceAspect { Around(annotation(dataSource)) public Object around(ProceedingJoinPoint point, DataSource dataSource) throws Throwable { String key dataSource.value(); DataSourceContextHolder.push(key); try { return point.proceed(); } finally { DataSourceContextHolder.poll(); } } }Order(Ordered.HIGHEST_PRECEDENCE)确保这个切面在所有其他切面之前执行避免事务切面先获取了连接再切换数据源导致失效。这个顺序问题是个大坑后面会详细说。3.5 验证切换是否生效写一个简单的测试Service来验证Service public class UserService { Autowired private JdbcTemplate jdbcTemplate; DataSource(master) public void insertUser(String name) { jdbcTemplate.update(INSERT INTO user(name) VALUES(?), name); } DataSource(slave) public ListMapString, Object queryUsers() { return jdbcTemplate.queryForList(SELECT * FROM user); } }启动应用后调用这两个方法通过日志或数据库监控确认写操作走了主库、读操作走了从库。如果两个库的数据不一致比如主从延迟查询结果能直观反映出切换是否生效。4. 那些只有踩过才知道的坑4.1 事务与数据源切换的顺序陷阱这是最容易出问题的地方。Spring的Transactional注解通过AOP实现在方法执行前就通过DataSourceTransactionManager获取了数据库连接并绑定到ThreadLocal中。如果数据源切换的切面在事务切面之后执行那么事务已经用默认数据源开启了连接后面的切换根本不会生效。解决方案是确保数据源切面的Order值小于事务切面的Order值。Spring事务切面的默认Order是Ordered.LOWEST_PRECEDENCE所以只要给数据源切面设置一个较小的值比如Ordered.HIGHEST_PRECEDENCE就能保证它先执行。但即使顺序对了还有一个更隐蔽的问题在同一个事务中切换数据源是无效的。因为事务一旦开启连接就已经确定了后续的切换只是改变了ThreadLocal的值但实际使用的连接不会变。如果业务确实需要在一个事务中操作多个库那只能考虑分布式事务方案或者把操作拆分成多个独立事务。4.2 异步线程中ThreadLocal的丢失ThreadLocal的值不会自动传递到子线程。如果Service方法中开启了异步任务异步线程里读取ThreadLocal会得到null导致数据源切换失效。这个问题在使用了线程池的场景下尤其常见。InheritableThreadLocal可以解决父子线程传递的问题但在线程池场景下依然无效——因为线程池中的线程是复用的创建时机不确定InheritableThreadLocal只在子线程创建时拷贝一次父线程的值。更可靠的方案是使用TransmittableThreadLocal阿里开源的TTL库它通过装饰Runnable/Callable在任务提交时捕获当前线程的ThreadLocal值在任务执行时恢复到执行线程中。如果不想引入额外依赖也可以在提交异步任务时手动传递数据源标识在异步任务内部重新set。虽然麻烦一点但胜在可控。4.3 连接池层面的数据源隔离多个数据源意味着多个连接池。如果每个数据源都配置了最大连接数总连接数就是各数据源之和。在数据库连接数有限的情况下需要合理分配每个池的大小。我见过一个配置主库和从库各配了50个最大连接结果数据库最大连接数只有100稍微一压测就报too many connections。另外从库通常承担读流量连接数可以适当多配一些主库主要承担写流量连接数可以少一些。具体数值要根据实际压测结果调整没有一个放之四海而皆准的公式。4.4 事务同步器与数据源切换的冲突Spring的TransactionSynchronizationManager在事务开启时会把连接资源绑定到ThreadLocal中。当数据源切换后如果事务同步器还持有旧数据源的连接资源就会出现切换了数据源但事务还在用旧连接的诡异现象。排查这类问题时可以在determineCurrentLookupKey()方法中打印当前线程名和ThreadLocal中的值同时在获取连接的地方打印实际使用的数据源标识对比两者是否一致。如果不一致基本可以确定是事务同步器的问题。5. 从单库到多租户动态数据源的扩展思路5.1 多租户场景下的数据源路由多租户系统的数据源切换逻辑和读写分离类似但key的来源不同。读写分离的key是固定的master或slave而多租户的key是租户ID需要在请求入口处从请求头、Token或域名中解析出来。一种常见的做法是在过滤器中解析租户ID然后调用DataSourceContextHolder.push(tenantId)。但这里有个问题租户数量可能很多不可能为每个租户都预先配置一个数据源。这时候需要换一种思路——不是为每个租户配置独立数据源而是根据租户ID计算出分片多个租户共享同一个物理库。AbstractRoutingDataSource的targetDataSources是一个Mapkey可以是任意对象。你可以把租户ID到数据源key的映射关系存在这个Map里也可以重写determineCurrentLookupKey()方法在里面根据租户ID动态计算出数据源key。5.2 动态增删数据源的运行时方案标准的AbstractRoutingDataSource在初始化后targetDataSources是不可变的。如果需要在运行时动态添加数据源比如新租户开通时自动创建数据库需要做一些扩展。思路是继承AbstractRoutingDataSource暴露一个addDataSource方法内部维护一个可变的Map并在添加后调用afterPropertiesSet()重新初始化。但要注意线程安全问题添加数据源时需要用ConcurrentHashMap或加锁保护。另一种更彻底的方案是不使用AbstractRoutingDataSource自己实现一个DataSource在getConnection()方法中根据ThreadLocal中的key从动态Map中查找数据源。这样灵活性更高但需要自己处理连接池的管理和生命周期。5.3 数据源健康检查与故障转移多个数据源意味着多个故障点。如果从库宕机了读请求应该自动降级到主库而不是直接报错。可以在determineCurrentLookupKey()中增加健康检查逻辑如果目标数据源不可用返回默认数据源。健康检查的实现方式有多种可以用连接池提供的检测机制也可以定时执行SELECT 1探活。关键是要把检查结果缓存起来避免每次获取连接都去探测那样性能开销太大。通常设置一个几十秒的缓存过期时间就足够了。5.4 监控与可观测性建设动态数据源切换的监控至少需要覆盖三个维度每个数据源的连接数使用情况、切换操作的频率和耗时、切换失败或降级的次数。这些指标可以通过Micrometer等工具暴露给监控系统。日志方面建议在determineCurrentLookupKey()中打debug日志记录线程名、当前数据源key和调用栈。线上出问题时这些日志是排查的第一手资料。但要注意日志量高并发场景下全量打印会拖慢性能可以加采样率控制。6. 几个值得关注的实现细节6.1 默认数据源的选择策略setDefaultTargetDataSource()设置的默认数据源在determineCurrentLookupKey()返回null时生效。大多数场景下默认数据源应该设为主库因为写操作对数据一致性要求更高读操作走从库即使出问题影响也相对小。但如果是读多写少的系统把默认数据源设为从库也未尝不可只是需要确保所有写操作都显式标注了DataSource(master)。这个选择没有绝对的对错取决于业务对一致性和性能的权衡。6.2 注解在类级别与方法级别的优先级DataSource注解可以标注在类上也可以标注在方法上。当两者同时存在时方法级别的注解应该优先。实现这个逻辑需要在AOP切面中先检查方法上是否有注解没有再去检查类上是否有。Around(within(com.example.annotation.DataSource) || annotation(com.example.annotation.DataSource)) public Object around(ProceedingJoinPoint point) throws Throwable { MethodSignature signature (MethodSignature) point.getSignature(); Method method signature.getMethod(); DataSource dataSource method.getAnnotation(DataSource.class); if (dataSource null) { dataSource point.getTarget().getClass().getAnnotation(DataSource.class); } // ... }这个细节虽然小但能让注解的使用更加灵活。比如整个Service类都走从库只需要在类上标注一次个别写方法再单独标注主库即可。6.3 与MyBatis插件的配合如果项目使用MyBatis还可以通过拦截器在SQL执行前根据SQL类型自动切换数据源。SELECT语句走从库INSERT、UPDATE、DELETE走主库。这种方式对业务代码完全无侵入但灵活性不如注解方式——比如某些对实时性要求高的查询即使走从库有延迟也必须走主库自动切换就无法满足这种需求。实际项目中注解方式和MyBatis插件方式可以结合使用默认由插件自动路由特殊场景用注解强制指定。这样既减少了手动标注的工作量又保留了精细控制的能力。6.4 单元测试中的数据源Mock测试动态数据源切换逻辑时不需要真的连数据库。可以MockDataSourceContextHolder的行为验证在调用不同方法时ThreadLocal中的值是否符合预期。对于AbstractRoutingDataSource的路由逻辑可以单独写测试类手动设置ThreadLocal的值然后断言determineCurrentLookupKey()的返回值。集成测试则需要真实的多个数据源通常用H2内存数据库模拟主库和从库通过不同的JDBC URL区分。测试完成后记得清理ThreadLocal避免测试用例之间相互影响。6.5 性能开销的实测数据ThreadLocal的set和get操作本质上是对当前线程内部Map的读写没有锁竞争单次操作在纳秒级别。AbstractRoutingDataSource的determineCurrentLookupKey()调用和Map查找也是常数时间复杂度。整体来看动态数据源切换带来的额外开销相对于一次数据库查询毫秒级完全可以忽略不计。真正可能影响性能的是连接池的配置和数据库本身的响应速度而不是切换逻辑本身。所以在这个方案上不需要过度优化把精力放在连接池调优和SQL优化上收益更大。6.6 与Spring Boot自动配置的整合Spring Boot的DataSourceAutoConfiguration默认只配置一个数据源。引入多数据源后需要排除自动配置或者用Primary标记动态数据源让自动配置以它为准。同时JdbcTemplate、MyBatis等组件的自动配置也需要确保注入的是动态数据源而不是某个物理数据源。一个常见的错误是JdbcTemplate自动注入了master数据源导致所有操作都走主库数据源切换完全失效。排查时可以在启动日志中搜索数据源初始化的相关信息确认各组件实际使用的是哪个数据源。6.7 数据源切换的边界条件有几种情况需要特别处理ThreadLocal中没有任何值时应该返回默认数据源数据源key在targetDataSources中不存在时应该抛出明确的异常而不是返回null导致空指针嵌套切换时内层方法结束后必须恢复到外层的值而不是直接清空。这些边界条件在正常流程中很少触发但一旦出问题往往很难排查。建议在determineCurrentLookupKey()中加上防御性判断和清晰的日志输出把问题暴露在早期而不是等到线上事故才发现。6.8 从ThreadLocal到Reactor Context的演进如果项目使用的是Spring WebFlux等响应式框架ThreadLocal就不再适用了因为一个请求可能在不同线程间流转。响应式编程中对应的解决方案是Reactor的Context它能在响应式链中传递上下文信息。虽然实现机制不同但核心思想是一致的在请求入口处绑定数据源标识在数据访问层读取这个标识请求结束后清理。理解ThreadLocal方案的本质有助于在切换技术栈时快速找到对应的替代方案。无论是ThreadLocal、InheritableThreadLocal、TransmittableThreadLocal还是ReactorContext解决的都是同一个问题如何在调用链中隐式传递上下文信息。我在实际项目中的体会是动态数据源切换这个功能代码量不大但细节极多。每一个看似简单的设计决策背后都可能隐藏着事务、线程、连接池层面的连锁反应。把上面这些坑都踩过一遍之后再回头看ThreadLocal和AbstractRoutingDataSource的源码会有一种豁然开朗的感觉——原来Spring早就把扩展点留好了只是需要理解它的运作机制才能用得恰到好处。
