多数据源切换DS 注解底层调用原理深度剖析一、概述DS注解来自dynamic-datasource-spring-boot-starter组件苞米豆出品并非 MyBatis-Plus 核心包而是其生态扩展。该注解用于在多数据源场景下声明式地指定当前方法/类使用哪个数据源。使用示例DS(xxx)// 切换到指定数据源Transactional(propagationPropagation.REQUIRES_NEW)publicclassOrderDaoImplextendsServiceImplOrderMapper,OrderEntity{// ...}二、核心组件与调用链2.1 整体架构DS 注解 │ ▼ DynamicDataSourceAnnotationInterceptor (AOP 拦截器) │ ▼ DynamicDataSourceClassResolver (解析注解确定数据源名称) │ ▼ DynamicDataSourceContextHolder (ThreadLocal 存储当前数据源标识) │ ▼ DynamicRoutingDataSource (继承 AbstractRoutingDataSource路由数据源) │ ▼ DataSourceProperty → HikariCP/Druid (实际物理数据源连接池)2.2 六大核心组件组件职责DS注解标记目标数据源名称DynamicDataSourceAnnotationInterceptorAOP MethodInterceptor拦截被DS标注的方法DynamicDataSourceClassResolver解析DS注解处理方法级/类级优先级DynamicDataSourceContextHolder基于 ThreadLocal 持有当前线程的数据源标识DynamicRoutingDataSource继承AbstractRoutingDataSource根据标识路由到真实数据源DataSourceProperty封装每个数据源的配置url、username、pool 等三、底层调用原理详解3.1 自动配置阶段dynamic-datasource-spring-boot-starter通过 Spring Boot 自动配置机制注册核心 Beanspring.factories / AutoConfiguration │ ├── DynamicDataSourceAutoConfiguration │ ├── 注册 DynamicDataSourceProperties读取 spring.datasource.dynamic.* 配置 │ ├── 注册 DynamicRoutingDataSource主数据源 Bean替换默认 DataSource │ ├── 注册 DynamicDataSourceAnnotationAdvisorAOP 切面 │ └── 注册各个数据源连接池master、slave、自定义等 │ └── DynamicDataSourceAopConfiguration └── 注册 DynamicDataSourceAnnotationInterceptor 切点关键点DynamicRoutingDataSource替换了 Spring 默认的DataSourceBean所有数据库操作都经过它路由。3.2 AOP 拦截阶段当调用被DS标注的方法时执行流程如下1. 调用方调用 DS 标注的方法 │ 2. DynamicDataSourceAnnotationInterceptor.invoke() │ 3. DynamicDataSourceClassResolver.findKey(method, targetClass) │ ┌─────────────────────────────────────────────┐ │ │ 注解查找优先级从高到低 │ │ │ ① 方法上的 DS │ │ │ ② 类上的 DS │ │ │ ③ 接口方法上的 DS │ │ │ ④ 接口类上的 DS │ │ │ ⑤ 默认数据源master │ │ └─────────────────────────────────────────────┘ │ 4. DynamicDataSourceContextHolder.push(key) │ 将数据源标识压入 ThreadLocal 栈支持嵌套切换 │ 5. 执行实际业务方法 → MyBatis 执行 SQL │ 6. DynamicRoutingDataSource.determineTargetDataSource() │ 从 ThreadLocal 取出当前数据源标识 │ 根据标识从 MapString, DataSource 中获取对应数据源 │ 7. 方法执行完毕 │ 8. DynamicDataSourceContextHolder.poll() │ 弹出栈顶数据源标识恢复上一层数据源3.3 核心源码逻辑1AOP 拦截器publicclassDynamicDataSourceAnnotationInterceptorimplementsMethodInterceptor{OverridepublicObjectinvoke(MethodInvocationinvocation)throwsThrowable{// 1. 解析当前方法/类上的 DS 注解获取数据源名称StringdsKeydynamicDataSourceClassResolver.findKey(invocation.getMethod(),invocation.getThis().getClass());// 2. 将数据源标识压入 ThreadLocalDynamicDataSourceContextHolder.push(dsKey);try{// 3. 执行实际方法此时 SQL 执行会走路由数据源returninvocation.proceed();}finally{// 4. 方法结束后弹出数据源标识恢复上层DynamicDataSourceContextHolder.poll();}}}2ThreadLocal 上下文持有者publicclassDynamicDataSourceContextHolder{// 使用栈结构支持嵌套 DS 调用privatestaticfinalThreadLocalDequeStringLOOKUP_KEY_HOLDERThreadLocal.withInitial(ArrayDeque::new);publicstaticvoidpush(Stringds){LOOKUP_KEY_HOLDER.get().push(ds);}publicstaticvoidpoll(){DequeStringdequeLOOKUP_KEY_HOLDER.get();deque.poll();if(deque.isEmpty()){LOOKUP_KEY_HOLDER.remove();}}publicstaticStringpeek(){returnLOOKUP_KEY_HOLDER.get().peek();}}栈结构的意义支持嵌套调用场景。例如方法 A 使用DS(master)其内部调用方法 B 使用DS(slave)执行 B 时压入 “slave”B 结束后弹出恢复 “master”。3路由数据源publicclassDynamicRoutingDataSourceextendsAbstractRoutingDataSource{// 存储所有数据源实例privateMapString,DataSourcedataSourceMap;OverrideprotectedObjectdetermineCurrentLookupKey(){// 从 ThreadLocal 获取当前数据源标识returnDynamicDataSourceContextHolder.peek();}OverrideprotectedDataSourcedetermineTargetDataSource(){StringlookupKey(String)determineCurrentLookupKey();DataSourcedataSourcedataSourceMap.get(lookupKey);if(dataSourcenull){thrownewDataSourceNotFoundException(数据源 [lookupKey] 未找到);}returndataSource;}}4注解解析器publicclassDynamicDataSourceClassResolver{publicStringfindKey(Methodmethod,Class?targetClass){// 优先级方法 类 接口方法 接口类// 1. 检查方法上的 DSDSdsmethod.getAnnotation(DS.class);if(ds!null)returnds.value();// 2. 检查类上的 DSdstargetClass.getAnnotation(DS.class);if(ds!null)returnds.value();// 3. 检查接口方法上的 DS// 4. 检查接口类上的 DS// ...// 5. 返回默认数据源returnmaster;}}四、与Transactional的协同与冲突4.1 典型用法DS(warehouse)Transactional(propagationPropagation.REQUIRES_NEW)publicclassOrderDaoImplextendsServiceImpl...{}4.2 执行顺序问题Spring 事务管理器和DSAOP 都基于代理执行顺序取决于Order顺序效果事务 AOP 先执行Order更小事务先绑定默认数据源的 ConnectionDS切换无效DSAOP 先执行Order更小先切换数据源事务在正确数据源上开启dynamic-datasource-spring-boot-starter默认将DS的 AOP 优先级设为Ordered.HIGHEST_PRECEDENCE确保先切换数据源再开启事务。4.3REQUIRES_NEW的作用Propagation.REQUIRES_NEW表示始终开启新事务挂起外层事务。结合DS使用时外层事务使用数据源 A进入OrderDaoImpl时DS先切换到warehouse数据源REQUIRES_NEW在warehouse数据源上开启新事务方法结束后新事务提交数据源恢复外层事务继续如果不用REQUIRES_NEW而用默认的REQUIRED外层事务已绑定了 master 数据源的 ConnectionDS切换可能不生效因为事务同步管理器已绑定 Connection。五、完整调用时序图Caller │ ├─① 调用 DS(warehouse) 标注的方法 │ ▼ DynamicDataSourceAnnotationInterceptor.invoke() │ ├─② findKey() → 解析 DS 注解 → 返回 warehouse │ ├─③ DynamicDataSourceContextHolder.push(warehouse) │ ThreadLocal 栈: [warehouse] │ ├─④ Spring TransactionInterceptor.invoke() │ │ │ ├─⑤ DynamicRoutingDataSource.determineTargetDataSource() │ │ 从 ThreadLocal 取 warehouse → 返回对应 DataSource │ │ │ ├─⑥ 从 warehouse DataSource 获取 Connection │ │ │ ├─⑦ 开启事务 (REQUIRES_NEW → 新事务) │ │ │ ├─⑧ 执行 MyBatis SQL → 使用 warehouse 连接 │ │ │ └─⑨ 提交/回滚事务 │ ├─⑩ DynamicDataSourceContextHolder.poll() │ ThreadLocal 栈: [] (恢复为空) │ └─⑪ 返回结果六、关键设计要点总结要点说明AOP 拦截基于MethodInterceptor拦截DS标注的方法ThreadLocal 栈使用栈结构存储数据源标识支持嵌套调用场景AbstractRoutingDataSource继承 Spring 的路由数据源抽象类运行时动态选择数据源注解优先级方法级 类级 接口方法级 接口类级 默认 masterAOP 顺序DS优先级最高确保先切换数据源再开启事务事务配合需注意Transactional与DS的 AOP 顺序REQUIRES_NEW可避免事务绑定冲突连接池隔离每个数据源拥有独立的连接池HikariCP/Druid互不影响七、数据源配置参考定义数据源常量publicclassDsName{publicstaticfinalStringMASTERmaster;// 主库publicstaticfinalStringSLAVEslave;// 只读库publicstaticfinalStringSTAR_ROCKSstarrocks;// StarRocks 分析库publicstaticfinalStringWAREHOUSEwarehouse;// 数据仓库}对应application.yml配置spring:datasource:dynamic:primary:masterdatasource:master:url:jdbc:mysql://host:3306/db_mainusername:xxxpassword:xxxslave:url:jdbc:mysql://host:3306/db_slavestarrocks:url:jdbc:mysql://host:9030/db_analyticswarehouse:url:jdbc:mysql://host:3306/db_warehouse八、常见问题与最佳实践8.1DS不生效的常见原因原因解决方案同类内部方法调用绕过代理将DS方法抽到独立 Bean或使用AopContext.currentProxy()TransactionalAOP 优先级高于DS确认dynamic-datasource版本 ≥ 3.x或手动指定Order在非 Spring 管理的线程中使用手动调用DynamicDataSourceContextHolder.push()/poll()DS标注在 private 方法上AOP 无法拦截 private 方法需改为 public 或提升到类级别8.2 最佳实践DS优先标注在类上减少遗漏整个类默认使用指定数据源方法级DS覆盖类级个别需要切换数据源的方法单独标注配合REQUIRES_NEW使用跨数据源调用时避免事务绑定冲突避免同类内部调用确保 AOP 代理生效嵌套DS调用栈结构自动处理无需手动管理
多数据源切换DS 注解底层调用原理深度剖析一、概述DS注解来自dynamic-datasource-spring-boot-starter组件苞米豆出品并非 MyBatis-Plus 核心包而是其生态扩展。该注解用于在多数据源场景下声明式地指定当前方法/类使用哪个数据源。使用示例DS(xxx)// 切换到指定数据源Transactional(propagationPropagation.REQUIRES_NEW)publicclassOrderDaoImplextendsServiceImplOrderMapper,OrderEntity{// ...}二、核心组件与调用链2.1 整体架构DS 注解 │ ▼ DynamicDataSourceAnnotationInterceptor (AOP 拦截器) │ ▼ DynamicDataSourceClassResolver (解析注解确定数据源名称) │ ▼ DynamicDataSourceContextHolder (ThreadLocal 存储当前数据源标识) │ ▼ DynamicRoutingDataSource (继承 AbstractRoutingDataSource路由数据源) │ ▼ DataSourceProperty → HikariCP/Druid (实际物理数据源连接池)2.2 六大核心组件组件职责DS注解标记目标数据源名称DynamicDataSourceAnnotationInterceptorAOP MethodInterceptor拦截被DS标注的方法DynamicDataSourceClassResolver解析DS注解处理方法级/类级优先级DynamicDataSourceContextHolder基于 ThreadLocal 持有当前线程的数据源标识DynamicRoutingDataSource继承AbstractRoutingDataSource根据标识路由到真实数据源DataSourceProperty封装每个数据源的配置url、username、pool 等三、底层调用原理详解3.1 自动配置阶段dynamic-datasource-spring-boot-starter通过 Spring Boot 自动配置机制注册核心 Beanspring.factories / AutoConfiguration │ ├── DynamicDataSourceAutoConfiguration │ ├── 注册 DynamicDataSourceProperties读取 spring.datasource.dynamic.* 配置 │ ├── 注册 DynamicRoutingDataSource主数据源 Bean替换默认 DataSource │ ├── 注册 DynamicDataSourceAnnotationAdvisorAOP 切面 │ └── 注册各个数据源连接池master、slave、自定义等 │ └── DynamicDataSourceAopConfiguration └── 注册 DynamicDataSourceAnnotationInterceptor 切点关键点DynamicRoutingDataSource替换了 Spring 默认的DataSourceBean所有数据库操作都经过它路由。3.2 AOP 拦截阶段当调用被DS标注的方法时执行流程如下1. 调用方调用 DS 标注的方法 │ 2. DynamicDataSourceAnnotationInterceptor.invoke() │ 3. DynamicDataSourceClassResolver.findKey(method, targetClass) │ ┌─────────────────────────────────────────────┐ │ │ 注解查找优先级从高到低 │ │ │ ① 方法上的 DS │ │ │ ② 类上的 DS │ │ │ ③ 接口方法上的 DS │ │ │ ④ 接口类上的 DS │ │ │ ⑤ 默认数据源master │ │ └─────────────────────────────────────────────┘ │ 4. DynamicDataSourceContextHolder.push(key) │ 将数据源标识压入 ThreadLocal 栈支持嵌套切换 │ 5. 执行实际业务方法 → MyBatis 执行 SQL │ 6. DynamicRoutingDataSource.determineTargetDataSource() │ 从 ThreadLocal 取出当前数据源标识 │ 根据标识从 MapString, DataSource 中获取对应数据源 │ 7. 方法执行完毕 │ 8. DynamicDataSourceContextHolder.poll() │ 弹出栈顶数据源标识恢复上一层数据源3.3 核心源码逻辑1AOP 拦截器publicclassDynamicDataSourceAnnotationInterceptorimplementsMethodInterceptor{OverridepublicObjectinvoke(MethodInvocationinvocation)throwsThrowable{// 1. 解析当前方法/类上的 DS 注解获取数据源名称StringdsKeydynamicDataSourceClassResolver.findKey(invocation.getMethod(),invocation.getThis().getClass());// 2. 将数据源标识压入 ThreadLocalDynamicDataSourceContextHolder.push(dsKey);try{// 3. 执行实际方法此时 SQL 执行会走路由数据源returninvocation.proceed();}finally{// 4. 方法结束后弹出数据源标识恢复上层DynamicDataSourceContextHolder.poll();}}}2ThreadLocal 上下文持有者publicclassDynamicDataSourceContextHolder{// 使用栈结构支持嵌套 DS 调用privatestaticfinalThreadLocalDequeStringLOOKUP_KEY_HOLDERThreadLocal.withInitial(ArrayDeque::new);publicstaticvoidpush(Stringds){LOOKUP_KEY_HOLDER.get().push(ds);}publicstaticvoidpoll(){DequeStringdequeLOOKUP_KEY_HOLDER.get();deque.poll();if(deque.isEmpty()){LOOKUP_KEY_HOLDER.remove();}}publicstaticStringpeek(){returnLOOKUP_KEY_HOLDER.get().peek();}}栈结构的意义支持嵌套调用场景。例如方法 A 使用DS(master)其内部调用方法 B 使用DS(slave)执行 B 时压入 “slave”B 结束后弹出恢复 “master”。3路由数据源publicclassDynamicRoutingDataSourceextendsAbstractRoutingDataSource{// 存储所有数据源实例privateMapString,DataSourcedataSourceMap;OverrideprotectedObjectdetermineCurrentLookupKey(){// 从 ThreadLocal 获取当前数据源标识returnDynamicDataSourceContextHolder.peek();}OverrideprotectedDataSourcedetermineTargetDataSource(){StringlookupKey(String)determineCurrentLookupKey();DataSourcedataSourcedataSourceMap.get(lookupKey);if(dataSourcenull){thrownewDataSourceNotFoundException(数据源 [lookupKey] 未找到);}returndataSource;}}4注解解析器publicclassDynamicDataSourceClassResolver{publicStringfindKey(Methodmethod,Class?targetClass){// 优先级方法 类 接口方法 接口类// 1. 检查方法上的 DSDSdsmethod.getAnnotation(DS.class);if(ds!null)returnds.value();// 2. 检查类上的 DSdstargetClass.getAnnotation(DS.class);if(ds!null)returnds.value();// 3. 检查接口方法上的 DS// 4. 检查接口类上的 DS// ...// 5. 返回默认数据源returnmaster;}}四、与Transactional的协同与冲突4.1 典型用法DS(warehouse)Transactional(propagationPropagation.REQUIRES_NEW)publicclassOrderDaoImplextendsServiceImpl...{}4.2 执行顺序问题Spring 事务管理器和DSAOP 都基于代理执行顺序取决于Order顺序效果事务 AOP 先执行Order更小事务先绑定默认数据源的 ConnectionDS切换无效DSAOP 先执行Order更小先切换数据源事务在正确数据源上开启dynamic-datasource-spring-boot-starter默认将DS的 AOP 优先级设为Ordered.HIGHEST_PRECEDENCE确保先切换数据源再开启事务。4.3REQUIRES_NEW的作用Propagation.REQUIRES_NEW表示始终开启新事务挂起外层事务。结合DS使用时外层事务使用数据源 A进入OrderDaoImpl时DS先切换到warehouse数据源REQUIRES_NEW在warehouse数据源上开启新事务方法结束后新事务提交数据源恢复外层事务继续如果不用REQUIRES_NEW而用默认的REQUIRED外层事务已绑定了 master 数据源的 ConnectionDS切换可能不生效因为事务同步管理器已绑定 Connection。五、完整调用时序图Caller │ ├─① 调用 DS(warehouse) 标注的方法 │ ▼ DynamicDataSourceAnnotationInterceptor.invoke() │ ├─② findKey() → 解析 DS 注解 → 返回 warehouse │ ├─③ DynamicDataSourceContextHolder.push(warehouse) │ ThreadLocal 栈: [warehouse] │ ├─④ Spring TransactionInterceptor.invoke() │ │ │ ├─⑤ DynamicRoutingDataSource.determineTargetDataSource() │ │ 从 ThreadLocal 取 warehouse → 返回对应 DataSource │ │ │ ├─⑥ 从 warehouse DataSource 获取 Connection │ │ │ ├─⑦ 开启事务 (REQUIRES_NEW → 新事务) │ │ │ ├─⑧ 执行 MyBatis SQL → 使用 warehouse 连接 │ │ │ └─⑨ 提交/回滚事务 │ ├─⑩ DynamicDataSourceContextHolder.poll() │ ThreadLocal 栈: [] (恢复为空) │ └─⑪ 返回结果六、关键设计要点总结要点说明AOP 拦截基于MethodInterceptor拦截DS标注的方法ThreadLocal 栈使用栈结构存储数据源标识支持嵌套调用场景AbstractRoutingDataSource继承 Spring 的路由数据源抽象类运行时动态选择数据源注解优先级方法级 类级 接口方法级 接口类级 默认 masterAOP 顺序DS优先级最高确保先切换数据源再开启事务事务配合需注意Transactional与DS的 AOP 顺序REQUIRES_NEW可避免事务绑定冲突连接池隔离每个数据源拥有独立的连接池HikariCP/Druid互不影响七、数据源配置参考定义数据源常量publicclassDsName{publicstaticfinalStringMASTERmaster;// 主库publicstaticfinalStringSLAVEslave;// 只读库publicstaticfinalStringSTAR_ROCKSstarrocks;// StarRocks 分析库publicstaticfinalStringWAREHOUSEwarehouse;// 数据仓库}对应application.yml配置spring:datasource:dynamic:primary:masterdatasource:master:url:jdbc:mysql://host:3306/db_mainusername:xxxpassword:xxxslave:url:jdbc:mysql://host:3306/db_slavestarrocks:url:jdbc:mysql://host:9030/db_analyticswarehouse:url:jdbc:mysql://host:3306/db_warehouse八、常见问题与最佳实践8.1DS不生效的常见原因原因解决方案同类内部方法调用绕过代理将DS方法抽到独立 Bean或使用AopContext.currentProxy()TransactionalAOP 优先级高于DS确认dynamic-datasource版本 ≥ 3.x或手动指定Order在非 Spring 管理的线程中使用手动调用DynamicDataSourceContextHolder.push()/poll()DS标注在 private 方法上AOP 无法拦截 private 方法需改为 public 或提升到类级别8.2 最佳实践DS优先标注在类上减少遗漏整个类默认使用指定数据源方法级DS覆盖类级个别需要切换数据源的方法单独标注配合REQUIRES_NEW使用跨数据源调用时避免事务绑定冲突避免同类内部调用确保 AOP 代理生效嵌套DS调用栈结构自动处理无需手动管理
