三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

深入解析dynamic-datasource：多数据源路由原理与事务管理实战

发布时间：2026/8/12 17:42:22 三亩地 编程学习日记
深入解析dynamic-datasource：多数据源路由原理与事务管理实战

1. 从“能用”到“懂用”：为什么需要拆解多数据源中间件

在Java后端开发，特别是基于Spring Boot构建的企业级应用中，多数据源是一个绕不开的经典需求。无论是读写分离、分库分表，还是对接多个异构数据库，我们都需要在同一个应用内优雅地管理多个DataSource。市面上成熟的解决方案不少，dynamic-datasource-spring-boot-starter（后文简称dynamic-datasource）因其与Spring Boot生态的无缝集成和简洁的配置，成为了许多开发者的首选。

但不知道你有没有遇到过这样的场景：配置了两个数据源，大部分查询正常，可某个使用了@Transactional注解的服务方法，偶尔会报出“找不到数据源”的错误；或者，在复杂的嵌套事务场景下，数据源切换似乎“失灵”了。这时候，如果你只是停留在“照着文档配一下就能跑通”的层面，排查问题会异常痛苦，只能靠猜测和反复重启。

这就是我决定深入dynamic-datasource源码的直接原因。我不满足于仅仅把它当作一个“黑盒”工具来使用。理解它的内部机制，意味着你能预判它的行为边界，在出现诡异问题时能快速定位根因，甚至能根据自身业务特点进行定制化扩展。比如，你是否清楚它如何与Spring的事务管理器PlatformTransactionManager协作？它的“数据源组”和“负载均衡策略”在底层是如何实现的？这些问题的答案，都藏在源码里。

本次分析，我将带你穿透dynamic-datasource简洁API的表面，深入到其设计核心。我们会重点关注它如何利用Spring的扩展点（如BeanPostProcessor、ImportBeanDefinitionRegistrar）来动态织入功能，如何通过AOP拦截实现方法级别的数据源切换，以及其事务管理方案中潜藏的“坑点”。目标不是罗列每一行代码，而是构建起对其核心运行机制的心智模型，让你下次遇到多数据源相关问题时，能胸有成竹。

2. 启动引擎：自动配置如何组装多数据源环境

当我们引入dynamic-datasource的依赖并在application.yml中写下spring.datasource.dynamic的配置时，魔法就开始了。这一切的起点是Spring Boot的自动配置机制。dynamic-datasource的核心自动配置类通常命名为DynamicDataSourceAutoConfiguration。

这个类上会标注@Configuration，并通过@EnableConfigurationProperties绑定以spring.datasource.dynamic为前缀的配置属性到一个配置类（例如DynamicDataSourceProperties）。这是第一步，将用户在YAML文件中的多数据源定义（主从、分组、连接池参数等）加载到内存中，形成结构化数据。

接下来是关键。自动配置类会利用@Bean方法，向Spring容器中注册几个核心的Bean：

2.1 数据源创建器与主数据源

首先，它会创建一个DataSourceCreator或其类似物。这个组件负责根据配置属性，使用指定的连接池（如HikariCP、Druid）实例化一个个具体的DataSourceBean。这里有个细节：虽然我们配置了多个数据源，但Spring Boot原生只认一个“主”数据源。dynamic-datasource的策略是，它会将配置中指定的primary数据源（默认为master），既注册为它自己管理的多数据源路由对象的一部分，同时也单独注册为一个名为dataSource的Bean。这样做是为了兼容那些直接依赖DataSource类型注入的第三方库或遗留代码，确保它们能无感知地工作。

2.2 核心路由数据源：DynamicRoutingDataSource

这是整个组件的“大脑”。它是一个实现了Spring标准AbstractRoutingDataSource的类。AbstractRoutingDataSource是Spring JDBC抽象层提供的一个模板类，其核心方法是determineCurrentLookupKey()，它的返回值决定了当前操作应该使用哪个实际的数据源。

DynamicRoutingDataSource内部维护了一个Map，键是数据源名称（如“master”、“slave_1”），值是对应的真实DataSource实例。在自动配置阶段，DataSourceCreator创建的所有数据源都会被添加到这个Map中。同时，DynamicRoutingDataSource自身也会被注册到Spring容器中，但通常不是以dataSource这个名字，而是以其类名或特定名称，以避免与上面提到的那个“主数据源”Bean冲突。

2.3 数据源初始化器与健康检查

自动配置通常还会包含一个DataSourceInitializer，用于在数据源创建后执行基础的SQL脚本（如建表语句）。更实用的是健康检查集成。它会向Spring Boot Actuator注册一个DataSourceHealthIndicator，但这是针对那个“主数据源”Bean的。对于多数据源的健康检查，dynamic-datasource可能会提供自定义的健康指示器，遍历所有托管的数据源进行检查，这需要查看其是否提供了相应的HealthContributor配置。

注意：自动配置的顺序有时很关键。如果项目中也引入了其他数据源相关的starter（比如某些ORM框架的自定义配置），可能会发生冲突。确保dynamic-datasource的配置在优先级上能正确覆盖或适配其他配置。一个常见的做法是在application.yml中明确使用spring.datasource.dynamic作为唯一的数据源配置入口，并禁用其他数据源自动配置（如spring.autoconfigure.exclude）。

3. 动态切换的魔法：AOP如何拦截并路由请求

配置好了数据源，但Spring的JdbcTemplate或MyBatis的SqlSession在执行SQL时，如何知道该用哪一个呢？这就是动态切换的核心逻辑，其实现依赖于Spring AOP（面向切面编程）。

3.1 切面定义与切入点

dynamic-datasource会定义一个或多个切面（Aspect），例如DataSourceAspect。这个切面使用@Around注解，其切入点（Pointcut）会瞄准所有标注了@DS注解的方法。@DS是dynamic-datasource提供的关键注解，你可以把它放在Service类或方法上，值为数据源名称，如@DS("slave")。

切入点的表达式可能类似于@annotation(com.baomidou.dynamic.datasource.annotation.DS)。这意味着，任何执行带有@DS注解的方法时，都会先经过这个切面的处理。

3.2 切面内的路由逻辑

在@Around通知的方法体内，切面会做以下几件事：

  1. 解析数据源键：通过连接点（JoinPoint）获取目标方法或其所在类上的@DS注解，解析出指定的数据源名称（例如“slave”）。
  2. 设置上下文：将这个数据源名称（键）设置到一个线程上下文中。dynamic-datasource通常使用一个ThreadLocal变量来存储这个键，例如DynamicDataSourceContextHolder.push(dsKey)。ThreadLocal确保了每个线程的切换是独立的，不会相互干扰，这是支持高并发场景的基础。
  3. 执行原方法：调用proceed()方法，执行实际的业务逻辑。
  4. 清理上下文：在finally块中，将当前线程的数据源键从上下文中移除（DynamicDataSourceContextHolder.poll()或clear()），防止内存泄漏和上下文污染。

3.3 AbstractRoutingDataSource 的配合

此时，真正的数据源获取还没发生。当MyBatis或JdbcTemplate需要获取连接时，它会向Spring请求一个DataSource。Spring会返回那个DynamicRoutingDataSource实例（因为它是主要的DataSource类型Bean）。

当DynamicRoutingDataSource的getConnection()方法被调用时，其父类AbstractRoutingDataSource的模板方法会开始工作。它会调用我们前面提到的determineCurrentLookupKey()方法。而这个方法的实现，通常就是去刚才那个ThreadLocal中获取当前线程设置的数据源键。

@Override protected Object determineCurrentLookupKey() { return DynamicDataSourceContextHolder.getDataSourceKey(); }

拿到键之后，AbstractRoutingDataSource就会从它内部维护的Map里，找到对应的真实DataSource实例，并调用它的getConnection()方法，最终返回一个具体的数据库连接。

3.4 无注解时的默认行为

如果方法上没有@DS注解怎么办？DynamicRoutingDataSource的determineCurrentLookupKey()方法在获取不到键时，会返回null。AbstractRoutingDataSource处理null键时，会使用默认的目标数据源，也就是我们在配置中指定的那个primary数据源。这就实现了“无感”降级。

实操心得：这里有一个非常重要的细节——切面的执行顺序。如果项目中还有其他的AOP（比如事务切面TransactionInterceptor），那么切面的顺序将直接影响行为。在Spring AOP中，切面默认按照Bean的名称字母顺序执行。但事务切面通常优先级很高。务必确保数据源切换切面在事务切面之前执行。因为事务管理器需要在获取连接之前就确定数据源，以便将连接绑定到当前事务。如果顺序反了，事务切面先执行，它去获取连接时，数据源键还没被设置，就会使用默认数据源，导致切换失效。dynamic-datasource通常通过@Order注解或实现Ordered接口来确保自己的切面拥有足够高的优先级（值更小）。

4. 与事务管理的爱恨纠葛：@Transactional 下的切换挑战

事务是数据源切换中最复杂、最容易踩坑的部分。Spring的声明式事务管理（@Transactional）本身也是通过AOP（TransactionInterceptor）实现的。当@Transactional遇到@DS，问题就来了。

4.1 事务连接绑定的基本原理

Spring事务管理的核心是TransactionSynchronizationManager。在一个事务开始时，事务管理器会从数据源获取一个连接，然后将这个连接绑定到当前线程（通过ThreadLocal）。在该事务生命周期内的所有数据库操作，都会尝试使用这个已绑定的连接，而不是每次都去重新获取。这保证了事务的原子性。

4.2 冲突场景分析

假设我们有一个服务方法：

@DS("slave") @Transactional public void businessMethod() { // 一些读操作 readFromSlave(); // 一些写操作 writeToMaster(); // 这里出问题了！ }

理想情况是，读走从库，写走主库。但实际会发生什么？

  1. 事务切面先执行（假设顺序未调整），开启事务。
  2. 事务管理器去获取连接。此时，数据源切换切面还未执行，determineCurrentLookupKey()返回null或默认键（比如“master”），于是事务绑定了一个到主库的连接。
  3. 数据源切换切面执行，将线程上下文键设置为“slave”。
  4. 执行readFromSlave()。当该方法内部获取连接时，determineCurrentLookupKey()返回“slave”。但是！由于事务已经开启并绑定了一个主库连接，Spring会优先使用已绑定的资源。因此，读操作实际上使用了主库的连接，数据源切换失效。
  5. 执行writeToMaster()，同理，它也会使用已绑定的主库连接，但这可能符合预期。

结果就是，整个方法都在主库上执行，@DS("slave")注解形同虚设。更糟糕的是，如果writeToMaster()内部标注了@DS("master")，在事务内它也无法切换。

4.3 dynamic-datasource 的解决方案

dynamic-datasource意识到了这个问题，并提供了自己的事务管理器实现，通常是一个继承了DataSourceTransactionManager的DynamicDataSourceTransactionManager。这个自定义事务管理器重写了doBegin()、doGetTransaction()等关键方法。

它的核心思路是：在事务开始时，就将数据源键（来自@DS或默认）作为事务资源的一部分保存起来。具体流程可能是：

  • 在doBegin()中，它不再直接从determineCurrentLookupKey()获取键，而是从一个提前设置好的地方（可能是另一个ThreadLocal，或者从当前方法调用链中解析@DS注解）获取最终决定用于此事务的数据源键。
  • 用这个键去获取真实的数据源和连接，并进行绑定。
  • 此后，在该事务内部，无论determineCurrentLookupKey()如何变化，都始终使用这个已绑定的连接。

4.4 依然存在的局限与坑点

即使有了自定义事务管理器，挑战依然存在：

  1. 嵌套事务与传播行为：在PROPAGATION_REQUIRES_NEW的传播行为下，会挂起当前事务并开启一个新事务。此时，新事务需要重新决定数据源。如果内部方法没有@DS注解，它应该继承外部事务的数据源，还是回退到默认主库？逻辑需要精心设计。
  2. 非事务方法调用事务方法：在同一个类中，一个没有@Transactional和@DS注解的方法A，调用同一个类中带有@Transactional和@DS("slave")的方法B。由于Spring AOP基于代理的特性，自调用会绕过代理，导致@Transactional和@DS注解全部失效。这是一个经典的Spring AOP陷阱，并非dynamic-datasource的bug，但在此场景下会暴露问题。
  3. 多线程环境：如果在事务内启用了新线程执行数据库操作，新线程无法继承父线程的数据源上下文（ThreadLocal是不可继承的）。操作会落到默认数据源上，可能导致数据错乱。

避坑指南：对于事务内的数据源切换，最稳健的实践是保持事务与方法的数据源一致。即，如果一个方法开启了事务，那么在这个事务边界内，最好只使用一个数据源。如果业务上必须在一个事务内访问多个数据源（即分布式事务，这已超出本地事务能力），则需要考虑引入Seata等分布式事务解决方案，而不是依赖dynamic-datasource的动态切换。对于读从写主的场景，更常见的做法是将读操作（@DS("slave")）和写操作（@DS("master")、@Transactional）拆分到不同的方法中，通过服务调用来组合，避免在单个事务方法内混用。

5. 进阶特性解析：数据源组、负载均衡与SPI扩展

除了基础的路由切换，dynamic-datasource还提供了一些进阶特性来应对更复杂的生产场景。

5.1 数据源组（Group）

在读写分离场景中，我们通常有多个从库。配置上，我们可能这样写：

spring: datasource: dynamic: primary: master datasource: master: url: ... slave_1: url: ... slave_2: url: ...

此时，使用@DS("slave_1")或@DS("slave_2")可以指定具体的从库。但更常见的需求是，我们想随机或轮询地使用从库组，而不是硬编码。dynamic-datasource支持数据源组的概念。你可以这样配置：

spring: datasource: dynamic: primary: master datasource: master: url: ... slave: group: slave_1: url: ... slave_2: url: ...

此时，slave不再是一个具体的数据源，而是一个组名。当你在方法上使用@DS("slave")时，框架需要从slave_1和slave_2中选一个。这就引出了负载均衡策略。

5.2 负载均衡策略

dynamic-datasource内置了多种负载均衡策略，用于在数据源组内选择具体实例，通常通过strategy配置项指定：

  • 轮询（LoadBalanceStrategy.ROUND_ROBIN）：依次选用组内数据源。
  • 随机（LoadBalanceStrategy.RANDOM）：随机选用。
  • 负载均衡策略（LoadBalanceStrategy.SESSION）：首次请求随机，之后同一会话（通常基于线程？这里需要看源码确认，有时只是简单的ThreadLocal缓存）固定使用同一个，适用于需要会话粘滞的场景。

在源码中，会有一个LoadBalanceStrategy接口及其实现类。在DynamicRoutingDataSource决定具体数据源时，如果发现查找的键对应的是一个组，则会调用负载均衡策略选择器，根据策略选择一个组内的具体数据源键，再进行下一步查找。

5.3 SPI扩展机制

一个优秀的中间件必须提供扩展能力。dynamic-datasource通常利用Java的SPI（Service Provider Interface）机制来允许用户自定义部分行为。

常见的扩展点包括：

  1. 数据源创建器（DataSourceCreator）：如果你使用的连接池不在默认支持列表（Hikari, Druid, Tomcat等）内，你可以实现自己的DataSourceCreator，并通过SPI文件（META-INF/services/...）注册，框架会自动发现并使用它来创建数据源实例。
  2. 负载均衡策略（LoadBalanceStrategy）：内置的轮询、随机不满足需求？你可以实现自己的策略，例如根据数据源的当前连接数进行加权选择，实现更智能的负载均衡。
  3. 动态数据源提供器（DynamicDataSourceProvider）：默认的数据源是从YAML文件静态加载的。你可以实现这个接口，从数据库、配置中心（如Nacos、Apollo）甚至ETCD中动态地获取和刷新数据源配置。这对于需要动态扩容从库的场景非常有用。

查看源码时，可以关注那些通过java.util.ServiceLoader加载服务的代码段，那里就是扩展点的入口。理解这些扩展点，能让你在遇到特殊需求时，不再局限于框架的现有能力。

6. 源码中的设计模式与可借鉴的架构思想

阅读dynamic-datasource的源码，不仅能解决具体问题，还能学到很多优雅的设计模式和架构思想，这些对于我们自己设计中间件或复杂业务模块非常有帮助。

6.1 模板方法模式（Template Method）

这个模式在Spring框架中无处不在，dynamic-datasource也深得其精髓。最典型的应用就是继承AbstractRoutingDataSource。父类AbstractRoutingDataSource定义了获取连接的算法骨架：getConnection() -> determineTargetDataSource() -> determineCurrentLookupKey()。子类DynamicRoutingDataSource只需要覆写determineCurrentLookupKey()这个抽象方法，提供获取当前数据源键的逻辑，就完成了整个动态路由的核心功能。这种模式将不变的部分（算法结构）封装在父类，将可变的部分（键的解析）延迟到子类，极大地提高了代码的复用性和扩展性。

6.2 责任链模式（Chain of Responsibility）

在处理数据源键的解析过程中，可能会涉及多个维度的判断：先看是否有强制指定的数据源（通过DS注解），再看是否有全局配置，最后回退到默认主库。虽然dynamic-datasource的代码可能没有显式地使用责任链数据结构，但其解析逻辑体现了责任链的思想：按优先级依次尝试多个解析器，直到其中一个成功返回。我们在设计配置解析、权限校验等流程时，可以借鉴这种思想，使处理流程清晰且易于扩展。

6.3 基于ThreadLocal的上下文管理

这是实现线程隔离数据源切换的基石。DynamicDataSourceContextHolder类内部使用ThreadLocal<String>（或ThreadLocal<Deque<String>以支持嵌套）来存储数据源键。这是一个非常经典和高效的线程上下文传递方案。但源码中也必须小心翼翼地处理这个ThreadLocal的清理工作，确保在finally块中执行poll()或remove()，否则在Web应用使用线程池时，会造成严重的数据错乱和内存泄漏。这提醒我们，任何使用ThreadLocal的地方，都必须配对上严谨的生命周期管理。

6.4 对Spring生态的深度集成

dynamic-datasource的成功很大程度上得益于它对Spring Boot“约定大于配置”理念的遵循。它通过：

  • @EnableAutoConfiguration：利用自动配置减少用户配置。
  • @ConfigurationProperties：绑定外部配置，类型安全且友好。
  • BeanPostProcessor/ImportBeanDefinitionRegistrar：在Bean生命周期的特定阶段进行干预，动态注册或修改Bean定义（例如，替换原生的DataSourceTransactionManager）。
  • @ConditionalOnClass/@ConditionalOnMissingBean：条件化配置，只在特定类存在或某个Bean缺失时才生效，避免了与其他组件的冲突。

学习它如何娴熟地运用这些Spring扩展点，能极大提升我们开发Spring Boot Starter或通用组件的能力。

7. 实战排坑：从源码角度诊断典型问题

理解了原理，我们就能像侦探一样，从源码层面推理和解决实际问题。下面分析几个典型案例。

7.1 问题一：在异步任务或新线程中，@DS注解失效

  • 现象：在@Async注解的方法内，或者手动new Thread()/线程池提交的任务中，@DS指定的数据源不生效，操作总是跑到主库。
  • 源码溯源：问题的核心在于DynamicDataSourceContextHolder使用的是ThreadLocal。而Spring的@Async和手动创建的线程，与当前请求线程是不同的线程，ThreadLocal变量无法自动传递。
  • 解决方案：
    1. 手动传递：在开启异步任务前，先获取当前数据源键（String dsKey = DynamicDataSourceContextHolder.peek();），然后在异步任务的Runnable或Callable最开始处，手动设置一次（DynamicDataSourceContextHolder.push(dsKey);），并在最后清理。
    2. 使用TransmittableThreadLocal（TTL）：如果项目复杂，异步调用层级深，可以考虑引入阿里的TransmittableThreadLocal来替换框架内部的ThreadLocal。但这需要修改dynamic-datasource源码，风险较高。更实际的做法是，在自定义的线程池任务装饰器（TaskDecorator）中完成上下文传递。Spring Boot允许我们配置ThreadPoolTaskExecutor的TaskDecorator，在这里面进行ThreadLocal值的设置和清理是最优雅的方式。

7.2 问题二：嵌套服务调用，内层@DS注解不生效

  • 现象：服务A的方法a()调用服务B的方法b()，a()上无@DS，b()上有@DS("slave")，但b()中的查询依然走到了主库。
  • 源码与原理分析：这很可能不是dynamic-datasource的bug，而是Spring AOP的经典限制。如果a()和b()在同一个类中，那么a()对b()的调用是类内部的直接调用，不会经过Spring创建的代理对象，因此b()上的所有AOP注解（包括@DS和@Transactional）都会失效。
  • 解决方案：
    1. 将方法b()移到另一个Service类中：这是最根本的解决方案，确保调用通过代理进行。
    2. 自注入（Self-injection）：在Service中注入自己的代理实例，然后通过这个代理实例调用内部方法。但这种方法会让代码显得古怪，不推荐作为常规手段。
    3. 从设计上审视，这种“无注解方法调用有注解方法”的场景是否合理，或许可以调整代码结构。

7.3 问题三：配置了多个从库组，但负载均衡没有生效

  • 现象：按照文档配置了slave组包含两个从库，但使用@DS("slave")时，似乎总是固定访问其中一个。
  • 排查思路：
    1. 检查配置：首先确认YAML配置中，slave下面确实是group，并且包含了多个子数据源定义。一个常见的笔误是写成了平级的多个slave数据源。
    2. 检查策略：确认spring.datasource.dynamic.strategy配置是否正确设置为loadbalance或具体的策略名（如round_robin）。默认策略可能是null或非负载均衡模式。
    3. 源码调试：在DynamicRoutingDataSource的determineDataSource()方法或负载均衡选择器相关方法中打断点。查看当键为“slave”时，框架是否识别到它是一个组，以及最终选择了哪个具体数据源。这能最直接地定位是配置解析问题，还是负载均衡逻辑问题。
    4. 会话粘滞：如果使用了SESSION策略，那么在同一会话（可能是同一线程的多次请求）中会固定使用一个数据源。需要理解你使用的策略的具体行为。

通过结合日志、调试和源码理解，大部分关于dynamic-datasource的疑难杂症都能找到清晰的解决路径。最关键的是，不再将其视为神秘的黑盒，而是知其然并知其所以然。

编程学习 学习日记 实战经验
← 返回列表