在实际企业级开发中随着业务数据量的增长读写分离、多库分表、冷热数据分离等需求越来越常见。本文基于SpringBoot 3 JDK 17 Druid MyBatis-Plus手把手带你实现一套优雅的动态多数据源方案支持注解切换和代码切换两种方式并兼容分表场景。目录一、背景与需求二、依赖准备三、YAML 配置文件四、核心组件实现4.1 动态数据源路由 DynamicDataSource4.2 数据源配置类 DataSourceConfig4.3 SlaveDataSource 注解4.4 切面 DataSourceAspect⚠️ Order(1) 的深意只支持 annotation 的局限五、两种切换方式实战5.1 注解方式定时任务落库5.2 代码方式方法内动态切换六、分表支持TableNameContext七、常见坑与最佳实践坑 1事务内切数据源无效坑 2异步/线程池中数据源丢失坑 3clearDataSource 遗漏坑 4Druid 监控页面重复冲突坑 5SpringBoot 3 javax vs jakarta八、方案总结九、写在最后一、背景与需求我们的项目中有两个数据库数据源数据库用途mastercic主库容器信息等核心业务数据slavegps从库存储 GPS 历史轨迹数据按容器 ID 分表面临的挑战同一业务方法内可能需要访问不同数据库先查主库的容器信息再查从库的轨迹数据。定时任务需要切换数据源批量落库时写入从库。分表场景从库中每个容器对应一张历史位置表需要动态表名。事务一致性切面必须能在Transactional之前执行否则数据源切换失效。下面进入正题。二、依赖准备pom.xml关键依赖parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.x/version /parent properties java.version17/java.version /properties dependencies !-- Web -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- AOP -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-aop/artifactId /dependency !-- Druid -- dependency groupIdcom.alibaba/groupId artifactIddruid-spring-boot-3-starter/artifactId version1.2.20/version /dependency !-- MyBatis-Plus -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-spring-boot3-starter/artifactId version3.5.5/version /dependency !-- MySQL -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId /dependency /dependencies⚠️注意SpringBoot 3 必须使用druid-spring-boot-3-starter普通的druid-spring-boot-starter会出现兼容问题。三、YAML 配置文件spring: datasource: # 主数据源 master: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://172.16.18.53:3306/cic?useUnicodetruecharacterEncodingutf-8useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue username: root password: Qynj0531! type: com.alibaba.druid.pool.DruidDataSource druid: initial-size: 5 min-idle: 5 max-active: 20 max-wait: 60000 validation-query: SELECT 1 test-while-idle: true test-on-borrow: false test-on-return: false stat-view-servlet: enabled: true url-pattern: /druid/* allow: 127.0.0.1 login-username: admin login-password: admin123 # 从数据源 slave: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://172.16.18.53:3306/gps?useUnicodetruecharacterEncodingutf-8useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue username: root password: Qynj0531! type: com.alibaba.druid.pool.DruidDataSource druid: initial-size: 5 min-idle: 5 max-active: 20 max-wait: 60000 validation-query: SELECT 1 test-while-idle: true test-on-borrow: false test-on-return: false stat-view-servlet: enabled: true url-pattern: /druid/* allow: 127.0.0.1 login-username: admin login-password: admin123四、核心组件实现4.1 动态数据源路由DynamicDataSource继承AbstractRoutingDataSource通过ThreadLocal保存当前线程的数据源标识public class DynamicDataSource extends AbstractRoutingDataSource { public static final String MASTER master; public static final String SLAVE slave; private static final ThreadLocalString contextHolder new ThreadLocal(); public static void setDataSource(String dataSource) { contextHolder.set(dataSource); } public static String getDataSource() { return contextHolder.get(); } public static void clearDataSource() { contextHolder.remove(); } Override protected Object determineCurrentLookupKey() { return getDataSource(); } }核心原理AbstractRoutingDataSource在每次获取连接时会调用determineCurrentLookupKey()决定用哪个数据源。返回null时使用defaultTargetDataSource。为什么用 ThreadLocal保证多线程并发时不会互相干扰。但要注意父子线程传递和线程池复用两种场景后面会讲。4.2 数据源配置类DataSourceConfigConfiguration MapperScan(basePackages com.cetcnav.mapper, sqlSessionTemplateRef sqlTemplate) public class DataSourceConfig { Bean(name masterDataSource) ConfigurationProperties(spring.datasource.master) public DataSource masterDataSource() { return DruidDataSourceBuilder.create().build(); } Bean(name slaveDataSource) ConfigurationProperties(spring.datasource.slave) public DataSource slaveDataSource() { return DruidDataSourceBuilder.create().build(); } Primary Bean(name dynamicDataSource) public DataSource dynamicDataSource( Qualifier(masterDataSource) DataSource masterDataSource, Qualifier(slaveDataSource) DataSource slaveDataSource) { DynamicDataSource dynamicDataSource new DynamicDataSource(); dynamicDataSource.setDefaultTargetDataSource(masterDataSource); MapObject, Object dataSourceMap new HashMap(2); dataSourceMap.put(DynamicDataSource.MASTER, masterDataSource); dataSourceMap.put(DynamicDataSource.SLAVE, slaveDataSource); dynamicDataSource.setTargetDataSources(dataSourceMap); return dynamicDataSource; } Bean public DataSourceTransactionManager transactionManager( Qualifier(dynamicDataSource) DataSource dataSource) { return new DataSourceTransactionManager(dataSource); } Bean public SqlSessionTemplate sqlTemplate( Qualifier(sqlSessionFactory) SqlSessionFactory sqlSessionFactory) { return new SqlSessionTemplate(sqlSessionFactory); } }几个关键点Primary必须加dynamicDataSource是最终暴露给 MyBatis 使用的数据源否则注入时会报多 Bean 冲突。ConfigurationProperties前缀要区分master对应spring.datasource.master自动装载 Druid 配置。setDefaultTargetDataSource不显式指定数据源时默认走主库。事务管理器绑定dynamicDataSource保证在事务中切换数据源也生效虽然不推荐事务内切库容易出现跨库一致性问题。4.3SlaveDataSource注解Target({ElementType.METHOD, ElementType.TYPE}) Retention(RetentionPolicy.RUNTIME) Documented Inherited public interface SlaveDataSource { }Target同时支持方法和类方便类级别默认走从库。Inherited让子类也能继承父类的注解。4.4 切面DataSourceAspectSlf4j Aspect Order(1) // 关键必须早于事务切面 Component public class DataSourceAspect { Pointcut(annotation(com.cetcnav.annotation.SlaveDataSource)) public void slaveDataSourcePointCut() {} Around(slaveDataSourcePointCut()) public Object around(ProceedingJoinPoint point) throws Throwable { MethodSignature signature (MethodSignature) point.getSignature(); SlaveDataSource slaveDataSource signature.getMethod().getAnnotation(SlaveDataSource.class); if (Objects.nonNull(slaveDataSource)) { DynamicDataSource.setDataSource(DynamicDataSource.SLAVE); log.debug(设置数据源为: {}, DynamicDataSource.SLAVE); } try { return point.proceed(); } finally { DynamicDataSource.clearDataSource(); } } }⚠️Order(1)的深意Spring 事务切面默认 Order 是Integer.MAX_VALUE。数据源切换切面必须比事务切面先执行否则事务启动时已经通过dynamicDataSource拿到了连接此时还是默认的 master。进入方法后再切 slave事务里的连接依然是 master切换失败。所以Order(1)或任何小于Integer.MAX_VALUE的值都可以越小越先执行。只支持annotation的局限当前 Pointcut 只匹配了方法级别的注解如果你把SlaveDataSource打在类上切面不会生效。推荐改写为Pointcut(annotation(com.cetcnav.annotation.SlaveDataSource) || within(com.cetcnav.annotation.SlaveDataSource)) public void slaveDataSourcePointCut() {}within用于匹配类级别的注解。五、两种切换方式实战5.1 注解方式定时任务落库Override SlaveDataSource public void batchSaveCachedData() { IteratorMap.EntryLong, QueueHistoryLocation iterator locationCache.locationCache.entrySet().iterator(); while (iterator.hasNext()) { Map.EntryLong, QueueHistoryLocation entry iterator.next(); QueueHistoryLocation queue entry.getValue(); if (queue null || queue.isEmpty()) { iterator.remove(); continue; } processQueueUntilEmpty(entry.getKey(), queue, iterator); } }只要方法上打了SlaveDataSource整个方法的数据库操作都会走从库代码零侵入。5.2 代码方式方法内动态切换有时候一个方法里既有主库操作又有从库操作注解就不够用了需要代码手动切换Override public ApiResponseObject getLocationHistory(LocationHistoryRequestDTo request) { try { // 1. 主库查询容器信息 ContainerInfo con containerInfoService.getByNo(request.getNo()); if (ObjectUtil.isEmpty(con)) { return ApiResponse.error(String.format(容器【%s】不存在, request.getNo())); } // 2. 确保从库中对应分表已存在 locationCache.ensureLocationTableExists(con.getId()); // 3. 切到从库 指定分表后缀 DynamicDataSource.setDataSource(DynamicDataSource.SLAVE); TableNameContext.setSuffix(String.valueOf(con.getId())); // 4. 组装分页参数 PageHistoryLocation pageParam; if (Boolean.TRUE.equals(request.getPageFlag())) { Integer pageNum request.getPage() ! null ? request.getPage() : 1; Integer pageSize request.getSize() ! null ? request.getSize() : 10; pageParam new Page(pageNum, pageSize); } else { Integer pageNum request.getPage() ! null ? request.getPage() : 1; pageParam new Page(pageNum, -1); // size -1 表示不分页 } // 5. 从库查询 IPageHistoryLocation data locationMapper.selectHistoryLocationPage(pageParam, request); return ApiResponse.success(data); } catch (Exception e) { log.error(查询历史位置失败no{}, error{}, request.getNo(), e.getMessage(), e); return ApiResponse.error(查询失败 e.getMessage()); } finally { // 6. 必须清理防止线程复用污染 DynamicDataSource.clearDataSource(); TableNameContext.clear(); } }关键点主库操作必须在setDataSource之前完成否则容器信息会去从库查。finally块中一定要clearDataSource()否则线程池复用时下一个请求可能还在用从库。TableNameContext是分表上下文类似DynamicDataSource的思路用 ThreadLocal 保存表名后缀。六、分表支持TableNameContext动态表名可以通过MyBatis-Plus 的DynamicTableNameInnerInterceptor实现Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); DynamicTableNameInnerInterceptor tableInterceptor new DynamicTableNameInnerInterceptor(); tableInterceptor.setTableNameHandler((sql, tableName) - { String suffix TableNameContext.getSuffix(); // 只对历史位置表追加后缀其它表保持原样 if (history_location.equals(tableName) suffix ! null) { return tableName _ suffix; } return tableName; }); interceptor.addInnerInterceptor(tableInterceptor); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }TableNameContext与DynamicDataSource类似public class TableNameContext { private static final ThreadLocalString SUFFIX new ThreadLocal(); public static void setSuffix(String suffix) { SUFFIX.set(suffix); } public static String getSuffix() { return SUFFIX.get(); } public static void clear() { SUFFIX.remove(); } }这样history_location表在 SQL 执行时会被自动改写为history_location_{containerId}业务代码无需关心物理表名。七、常见坑与最佳实践坑 1事务内切数据源无效Transactional public void doSomething() { // 事务已经开启绑定的是 master 连接 DynamicDataSource.setDataSource(slave); // 这里的 SQL 依然走 master }原因Spring 事务会在方法执行前绑定 Connection中途切换RoutingDataSource不会重新获取连接。建议不要把跨库操作放在同一个事务里。如果一定要考虑 Atomikos / Seata 等分布式事务方案。坑 2异步/线程池中数据源丢失DynamicDataSource.setDataSource(slave); CompletableFuture.runAsync(() - { // 这里 ThreadLocal 拿不到回落到默认 master locationMapper.selectXxx(); });解决使用TransmittableThreadLocal阿里 TTL替代ThreadLocal或者在线程池任务开始处手动setDataSource。坑 3clearDataSource遗漏try { DynamicDataSource.setDataSource(slave); // 业务代码 } catch (Exception e) { // 忘记 finally clear }Tomcat 线程池会复用线程下一个请求可能在不知不觉中走了从库。必须放在finally。坑 4Druid 监控页面重复冲突两个数据源如果都启用了stat-view-servlet会报url-pattern冲突。推荐只在一个数据源上启用或显式配置不同的url-pattern。坑 5SpringBoot 3 javaxvsjakarta升级到 SpringBoot 3 后切面、事务等自动配置的包名全部切到jakarta.*Druid 需要选druid-spring-boot-3-starterMyBatis-Plus 需要选mybatis-plus-spring-boot3-starter。八、方案总结特性支持情况注解切换数据源✅SlaveDataSource代码切换数据源✅DynamicDataSource.setDataSource()分库✅ master / slave 双库分表✅DynamicTableNameInnerInterceptor事务兼容⚠️ 需注意切面 Order 与跨库事务异步线程支持⚠️ 需 TTL 或手动传递Druid 监控✅/druid/*整体架构图┌────────────────────────────────────────────────┐ │ Business Service │ │ SlaveDataSource / setDataSource(slave) │ └───────────────────┬────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────┐ │ DataSourceAspect (Order(1)) │ │ ThreadLocalDataSource │ └───────────────────┬────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────┐ │ DynamicDataSource (AbstractRoutingDataSource)│ │ ┌────────────┐ ┌────────────┐ │ │ │ master │ │ slave │ │ │ │ DruidPool │ │ DruidPool │ │ │ └────────────┘ └────────────┘ │ └───────────────────┬────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────┐ │ MyBatis-Plus DynamicTableNameInterceptor │ │ history_location → history_location_{cid} │ └────────────────────────────────────────────────┘九、写在最后动态多数据源看似简单其实细节非常多切面顺序、ThreadLocal 清理、事务边界、异步传递、分表联动任何一环出错都可能产生线上事故。本文的方案是经过实际项目验证的覆盖了读写分离、定时任务切换、分表查询等典型场景。如果你的项目也有类似需求可以直接参考落地。如果这篇文章帮你避开了几个坑欢迎点赞 收藏 关注后续我会继续分享 Seata 分布式事务、ShardingSphere 分库分表等进阶内容。 本文代码基于SpringBoot 3.2 JDK 17 Druid 1.2.20 MyBatis-Plus 3.5.5不同版本可能存在细节差异请以实际项目为准。