简介本资源是面向Java后端开发者与Spring Boot进阶学习者的动态多数据源解决方案聚焦读写分离、数据库分片及高可用架构等企业级场景有效解决单应用对接多个异构数据库的配置复杂、切换低效问题。压缩包共170个文件含138个核心Java类如DynamicRoutingDataSource、ConnectionProxy、6个SQL脚本用于环境初始化、6个XML配置模板、5个JSON配置示例以及说明.htm文档和application.yml等关键配置文件整体仅273KB轻量易集成。已有245人下载学习适合希望深入理解Spring Boot Starter机制、掌握动态数据源底层原理如路由策略、事务兼容性、自动装配逻辑的开发者。源码结构清晰涵盖AutoConfiguration.imports、spring.factories注册点、AOP切面实现及CryptoUtils等安全工具类可直接复用或二次开发是学习Spring Boot扩展开发与多数据源工程实践的优质参考材料。1. 为什么 Spring Boot 启动时连不上第二个数据库dynamic datasource 多数据源启动器 v4.3.0 解决的不是“配多个数据源”而是“按需激活、零侵入切换、启动期自动装配”的真实痛点很多团队在 Spring Boot 项目里硬编码两个Bean数据源再套一层AbstractRoutingDataSource手写路由逻辑结果一加事务就报Could not obtain transaction-synchronized Session for current thread或者用DS(slave)注解却发现切面没生效、AOP 代理丢失、MyBatis 的SqlSessionTemplate拿到的还是默认数据源。这不是配置漏了是启动阶段的数据源注册顺序、自动配置加载时机、条件化装配ConditionalOnMissingBean与spring.factories旧机制的冲突被掩盖了。dynamic datasource 多数据源启动器 v4.3.0 正是为解决这类「启动即失效」问题而生它不依赖用户手写DataSourceBean也不要求改application.yml里的spring.datasource.*前缀而是通过AutoConfiguration.imports声明式导入核心自动配置类在 Spring Boot 2.7 的新自动装配模型下确保DynamicRoutingDataSource、DynamicDataSourceAutoConfiguration、DruidDynamicDataSourceAutoConfiguration若引入 Druid等组件在DataSourceAutoConfiguration之后、JpaAutoConfiguration之前精准注入。它面向的是已有单数据源项目想平滑接入读写分离、分库分表或异构数据库如 MySQL PostgreSQL的中大型系统而非教学 Demo。2. 从AutoConfiguration.imports入口切入v4.3.0 如何绕过spring.factories的加载竞争让动态数据源在 Spring Boot 2.7 启动链中稳占一席2.1 为什么 v4.3.0 放弃spring.factories改用META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.importsSpring Boot 2.7 开始spring.factories中的org.springframework.boot.autoconfigure.EnableAutoConfiguration键已被标记为Deprecated其加载优先级低、无法参与条件化排序且与AutoConfiguration注解的元数据解析存在竞态——当多个 starter 都声明DataSourceAutoConfiguration时spring.factories加载顺序不可控极易导致DynamicRoutingDataSource被HikariDataSource覆盖。v4.3.0 将自动配置类路径写入AutoConfiguration.imports该文件由SpringBootAutoConfigurationImportSelector统一解析支持AutoConfiguration的before/after属性声明依赖顺序。查看其 JAR 包内META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件内容com.baomidou.dynamic.datasource.spring.boot.autoconfigure.DynamicDataSourceAutoConfiguration com.baomidou.dynamic.datasource.spring.boot.autoconfigure.DynamicDataSourceCreatorAutoConfiguration com.baomidou.dynamic.datasource.spring.boot.autoconfigure.DynamicDataSourceProviderAutoConfiguration提示DynamicDataSourceAutoConfiguration是主配置类它通过AutoConfigureBefore(DataSourceAutoConfiguration.class)确保自身在DataSourceAutoConfiguration初始化前完成DynamicRoutingDataSource的 Bean 定义而DynamicDataSourceCreatorAutoConfiguration负责根据spring.datasource.dynamic.datasource.*下的配置项批量创建底层物理数据源如master,slave1,slave2并注入DataSourceProvider。2.2DynamicDataSourceAutoConfiguration的三个关键Bean及其生命周期钩子该配置类定义了三个核心 Bean它们共同构成动态数据源的启动骨架Configuration(proxyBeanMethods false) AutoConfigureBefore(DataSourceAutoConfiguration.class) EnableConfigurationProperties(DynamicDataSourceProperties.class) public class DynamicDataSourceAutoConfiguration { Bean ConditionalOnMissingBean public DataSource dynamicDataSource( DynamicDataSourceProperties properties, ObjectProviderDataSourceProvider provider) { DynamicRoutingDataSource router new DynamicRoutingDataSource(); // 1. 设置默认数据源名非 Bean 名 router.setDefaultTargetDataSource(provider.getObject().getDataSource(properties.getPrimary())); // 2. 设置所有目标数据源 Map router.setTargetDataSources(provider.getObject().getDataSources()); // 3. 设置数据源加载器支持运行时新增 router.setDataSourceLoader(new DefaultDataSourceLoader()); return router; } Bean ConditionalOnMissingBean public DataSourceProvider dataSourceProvider( DynamicDataSourceProperties properties, ObjectProviderListDataSourceCreator creators) { return new DefaultDataSourceProvider(properties, creators); } Bean ConditionalOnMissingBean public DataSourceCreator hikariDataSourceCreator() { return new HikariDataSourceCreator(); } }dynamicDataSource返回DynamicRoutingDataSource实例它继承自AbstractRoutingDataSource但重写了determineCurrentLookupKey()方法使其从DynamicDataSourceContextHolder的ThreadLocal中读取当前线程绑定的数据源 key如slave1而非仅依赖lookupKey。dataSourceProvider负责解析spring.datasource.dynamic.datasource.master.urljdbc:mysql://...这类多层级配置调用DataSourceCreator创建物理数据源并缓存到ConcurrentHashMapString, DataSource中。hikariDataSourceCreator默认提供 HikariCP 创建器若项目已引入 Druid则DruidDynamicDataSourceAutoConfiguration会通过ConditionalOnClass(DruidDataSource.class)替换此 Bean无需额外配置。2.3DynamicDataSourceProperties的结构设计为什么dynamic.datasource是独立命名空间且支持嵌套datasource.*v4.3.0 明确将动态数据源配置隔离在spring.datasource.dynamic.*下避免与 Spring Boot 原生spring.datasource.*冲突。其DynamicDataSourceProperties类结构如下精简关键字段配置项类型默认值说明spring.datasource.dynamic.primaryStringmaster启动时默认使用的数据源名称必须存在于datasource.*子节点中spring.datasource.dynamic.strictbooleanfalse设为true时若DS(xxx)指定的数据源不存在启动直接失败推荐测试环境开启spring.datasource.dynamic.separationbooleantrue是否启用数据源隔离即每个数据源使用独立的DataSourceTransactionManagerspring.datasource.dynamic.datasource.master.urlString—物理数据源master的 JDBC URL同理可配slave1,slave2等spring.datasource.dynamic.datasource.master.driver-class-nameString自动推断驱动类名Hikari 默认支持 MySQL/PostgreSQL/H2 等自动识别spring.datasource.dynamic.datasource.master.hikari.*Map—Hikari 专属参数如maximum-pool-size20会透传给HikariDataSourceCreator注意datasource.*是MapString, DataSourceProperty类型DataSourceProperty内部封装了url,username,password,driverClassName,hikari,druid等子属性。这意味着你可以在application.yml中这样写spring: datasource: dynamic: primary: master datasource: master: url: jdbc:mysql://127.0.0.1:3306/db_master?useSSLfalse username: root password: 123456 hikari: maximum-pool-size: 15 slave1: url: jdbc:mysql://127.0.0.1:3306/db_slave1?useSSLfalse username: reader password: 654321 hikari: maximum-pool-size: 83. 启动验证三步法用ApplicationContext和DataSource接口确认 v4.3.0 是否真正接管了数据源装配3.1 第一步检查DynamicRoutingDataSource是否成为DataSource类型的唯一 BeanSpring Boot 启动后若DynamicRoutingDataSource成功注册它应是ApplicationContext中类型为javax.sql.DataSource的唯一 BeanPrimary且ConditionalOnMissingBean生效。执行以下代码验证SpringBootApplication public class Application { public static void main(String[] args) { ConfigurableApplicationContext context SpringApplication.run(Application.class, args); // 获取所有 DataSource 类型的 Bean 名称 String[] dataSourceBeans context.getBeanNamesForType(DataSource.class); System.out.println(DataSource beans: Arrays.toString(dataSourceBeans)); // ✅ 正确输出[dynamicDataSource]注意 Bean 名为 dynamicDataSource非 dataSource // 获取 dynamicDataSource Bean 并检查类型 DataSource ds context.getBean(dynamicDataSource, DataSource.class); System.out.println(Bean type: ds.getClass().getName()); // ✅ 正确输出com.baomidou.dynamic.datasource.DynamicRoutingDataSource // 检查是否为 AbstractRoutingDataSource 子类关键 System.out.println(Is routing: (ds instanceof AbstractRoutingDataSource)); // ✅ 必须为 true否则路由逻辑不生效 } }若输出中出现dataSource来自DataSourceAutoConfiguration、hikariDataSource等其他 Bean说明DynamicDataSourceAutoConfiguration未生效大概率是AutoConfiguration.imports文件未被正确打包进 JAR或dynamic-datasource-spring-boot-starter依赖版本与 Spring Boot 不兼容v4.3.0 要求 Spring Boot 2.7。3.2 第二步验证DynamicRoutingDataSource的targetDataSources是否已加载全部物理数据源DynamicRoutingDataSource的targetDataSources字段是MapObject, Objectkey 为数据源名称如mastervalue 为实际的HikariDataSource或DruidDataSource。通过反射获取该 Map 并打印DynamicRoutingDataSource router context.getBean(DynamicRoutingDataSource.class); Field targetDataSourcesField AbstractRoutingDataSource.class.getDeclaredField(targetDataSources); targetDataSourcesField.setAccessible(true); MapObject, Object targetDataSources (MapObject, Object) targetDataSourcesField.get(router); System.out.println(Target data sources: targetDataSources.keySet()); // ✅ 正确输出[master, slave1]与 application.yml 中配置的 datasource.* 一致提示若targetDataSources为空或只含defaultTargetDataSource说明DataSourceProvider未成功解析配置。此时检查DynamicDataSourceProperties是否被正确注入——可在DynamicDataSourceAutoConfiguration的dynamicDataSource方法上打断点观察properties.getDatasource()返回的Map是否包含master和slave1。3.3 第三步运行时触发一次DS切换抓取determineCurrentLookupKey()的返回值DynamicRoutingDataSource的路由能力最终取决于determineCurrentLookupKey()方法的返回值。该方法内部调用DynamicDataSourceContextHolder.peek()从ThreadLocalString中读取当前线程绑定的 key。我们可通过 AOP 在 DAO 方法执行前插入日志Aspect Component public class DataSourceRouteAspect { Around(annotation(org.springframework.transaction.annotation.Transactional)) public Object logDataSourceKey(ProceedingJoinPoint joinPoint) throws Throwable { String key DynamicDataSourceContextHolder.peek(); System.out.println(Current DS key in TX: key); return joinPoint.proceed(); } }然后写一个简单 ServiceService public class UserService { Resource private UserMapper userMapper; Transactional DS(slave1) public ListUser findReaders() { return userMapper.selectAll(); // 触发查询 } }启动应用并调用findReaders()控制台应输出Current DS key in TX: slave1且数据库连接池监控如 Actuator/actuator/metrics/datasource.hikaricp.connections.active显示slave1的活跃连接数上升。若输出null或master说明DS(slave1)注解未被DynamicDataSourceAnnotationAdvisor拦截——这通常是因为dynamic-datasource-spring-boot-starter未正确引入或EnableAspectJAutoProxy(exposeProxy true)缺失v4.3.0 要求暴露代理以便DS在内部方法调用时生效。4.DS注解失效的四大根因与对应修复命令从类路径扫描到代理暴露的全链路排查4.1 根因一DS注解未被DynamicDataSourceAnnotationAdvisor织入表现为DS(xxx)完全无反应DynamicDataSourceAnnotationAdvisor是 v4.3.0 提供的切面增强器它依赖EnableAspectJAutoProxy启用。若项目中未显式配置Spring Boot 默认exposeProxy false导致DS在this.xxx()内部调用时失效。修复方式是在主启动类添加SpringBootApplication EnableAspectJAutoProxy(exposeProxy true) // ✅ 必须添加 public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }提示exposeProxy true会让AopContext.currentProxy()返回当前代理对象DynamicDataSourceAnnotationAdvisor内部正是通过此方式在DS方法内调用其他DS方法时保持路由上下文。若不开启DS仅对 Controller → Service 的跨 Bean 调用有效Service 内部方法调用会丢失。4.2 根因二DynamicDataSourceAutoConfiguration被ConditionalOnMissingBean拦截导致dynamicDataSourceBean 未注册常见于项目中已存在Bean方式定义的DataSource。v4.3.0 的ConditionalOnMissingBean默认检查DataSource类型若存在任何DataSourceBean包括HikariDataSource则跳过自身装配。解决方案是排除原生DataSourceAutoConfiguration# application.yml spring: autoconfigure: exclude: - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration或在SpringBootApplication中声明SpringBootApplication(exclude {DataSourceAutoConfiguration.class})注意排除后spring.datasource.*下的配置如url,username将不再生效所有数据源必须通过spring.datasource.dynamic.datasource.*配置否则启动报错。4.3 根因三DynamicRoutingDataSource的determineCurrentLookupKey()返回null导致 fallback 到defaultTargetDataSourceDynamicRoutingDataSource的determineCurrentLookupKey()方法源码如下Override protected Object determineCurrentLookupKey() { String key DynamicDataSourceContextHolder.peek(); if (key null) { key this.defaultTargetDataSourceName; // ✅ fallback 到 defaultTargetDataSourceName } return key; }defaultTargetDataSourceName默认为properties.getPrimary()即master但若peek()返回null说明DS切面未执行或DynamicDataSourceContextHolder未被正确设置。此时需检查DynamicDataSourceAnnotationInterceptor是否被加载# 启动时添加 JVM 参数查看自动配置报告 -Ddebug在控制台搜索DynamicDataSourceAutoConfiguration确认其状态为matched匹配而非not matched。若为not matched检查DynamicDataSourceProperties是否被EnableConfigurationProperties正确绑定——v4.3.0 要求DynamicDataSourceProperties必须被ConfigurationProperties(spring.datasource.dynamic)注解且EnableConfigurationProperties(DynamicDataSourceProperties.class)已在DynamicDataSourceAutoConfiguration中声明。4.4 根因四DataSourceBean 名冲突Primary被覆盖导致事务管理器绑定错误Spring 的DataSourceTransactionManager默认查找Primary的DataSource。若dynamicDataSourceBean 名为dynamicDataSource但Primary注解未生效事务可能仍走原始HikariDataSource。验证方式DataSourceTransactionManager tm context.getBean(DataSourceTransactionManager.class); System.out.println(TX managers DataSource: tm.getDataSource().getClass().getName()); // ✅ 应输出 com.baomidou.dynamic.datasource.DynamicRoutingDataSource若输出com.zaxxer.hikari.HikariDataSource说明DataSourceTransactionManager绑定了错误的DataSource。强制指定事务管理器 BeanBean Primary public DataSourceTransactionManager transactionManager(Qualifier(dynamicDataSource) DataSource dataSource) { return new DataSourceTransactionManager(dataSource); }提示Qualifier(dynamicDataSource)明确指向 v4.3.0 创建的 Bean避免Primary语义歧义。此 Bean 必须与DynamicDataSourceAutoConfiguration同一配置类中声明或确保其加载顺序在后者之后。5. 生产就绪技巧用DynamicDataSourceProviderAPI 动态注册新数据源实现不停机接入分库实例5.1DynamicDataSourceProvider的addDataSource方法运行时注入新数据源的唯一安全入口v4.3.0 提供DynamicDataSourceProvider接口其默认实现DefaultDataSourceProvider支持运行时增删数据源。关键方法签名public interface DynamicDataSourceProvider { /** * 添加数据源 * param name 数据源名称如 shard_001 * param property 数据源配置属性 * return 是否添加成功 */ boolean addDataSource(String name, DataSourceProperty property); /** * 移除数据源 * param name 数据源名称 * return 是否移除成功 */ boolean removeDataSource(String name); }addDataSource内部会调用DataSourceCreator创建物理数据源并将其 put 到DynamicRoutingDataSource.targetDataSources中同时刷新AbstractRoutingDataSource的resolvedDataSources缓存。这是唯一推荐的运行时注册方式避免直接操作targetDataSources导致线程安全问题。5.2 实现一个 HTTP 端点接收 JSON 配置并动态添加分库数据源RestController RequestMapping(/api/ds) public class DynamicDataSourceController { Resource private DynamicDataSourceProvider dataSourceProvider; Resource private DynamicRoutingDataSource dynamicRoutingDataSource; PostMapping(/add) public ResponseEntityString addDataSource(RequestBody DataSourceConfig config) { try { DataSourceProperty property new DataSourceProperty(); property.setUrl(config.getUrl()); property.setUsername(config.getUsername()); property.setPassword(config.getPassword()); property.setDriverClassName(config.getDriverClassName()); // Hikari 参数透传 MapString, String hikariProps new HashMap(); hikariProps.put(maximum-pool-size, String.valueOf(config.getMaximumPoolSize())); hikariProps.put(connection-timeout, String.valueOf(config.getConnectionTimeout())); property.setHikari(hikariProps); boolean success dataSourceProvider.addDataSource(config.getName(), property); if (success) { // ✅ 强制刷新路由缓存v4.3.0 必须调用 dynamicRoutingDataSource.afterPropertiesSet(); return ResponseEntity.ok(Added: config.getName()); } else { return ResponseEntity.status(400).body(Failed to add: config.getName()); } } catch (Exception e) { return ResponseEntity.status(500).body(Error: e.getMessage()); } } // 请求体示例 public static class DataSourceConfig { private String name; private String url; private String username; private String password; private String driverClassName; private int maximumPoolSize 10; private long connectionTimeout 30000; // getters setters... } }注意dynamicRoutingDataSource.afterPropertiesSet()是 v4.3.0 新增的强制刷新方法它会重新调用buildResolvedDataSources()将新加入的targetDataSources同步到resolvedDataSources缓存中。若不调用新数据源虽存在于targetDataSources但determineCurrentLookupKey()仍无法路由到它。5.3 验证动态数据源是否可被DS正确路由及事务管理调用上述接口添加shard_001后立即测试Service public class ShardService { DS(shard_001) public void testShard() { // 执行任意 SQL如 SELECT 1 jdbcTemplate.queryForObject(SELECT 1, Integer.class); } }同时监控 Actuator 指标/actuator/metrics/datasource.hikaricp.connections.active?tagpool.name:shard_001应有活跃连接/actuator/metrics/jvm.threads.live确认无线程泄漏动态注册不会创建新线程提示动态添加的数据源不参与启动期健康检查DataSourceHealthIndicator若需监控需自行扩展HealthIndicator实现遍历dynamicRoutingDataSource.getTargetDataSources().values()获取各物理数据源的健康状态。本文还有配套的精品资源点击获取