primary数据源配置排查：dynamic-datasource报错解决指南-北京尧图网络

1. 先搞懂 primary 在 dynamic-datasource 里到底承担什么角色1.1 dynamic-datasource 不是“多个数据源”而是“一个路由数据源”很多第一次用dynamic-datasource的人都会被名字带偏以为它就是在 Spring Boot 里配了两个DataSourceBean需要哪个就Autowired哪个。实际上完全不是这么回事。dynamic-datasource 的核心思想是对外提供一个统一的路由数据源内部维护一张“数据源路由表”用字符串 key 来区分不同的真实数据源。你写的所有 SQL 都先经过这个路由层再由路由层根据当前线程上下文决定到底发给哪个底层数据源。在这样的设计里primary不是“主库”的意思而是“默认路由 key”。当业务方法上没有标注DS或者当前线程上下文里压根没有写入任何数据源 key路由层必须有一个兜底选择。这个兜底就是 primary。如果路由表里连这个兜底 key 都不存在组件就直接抛出dynamic-datasource can not find primary datasource。注意这里的“找不到 primary”不是说你的 MySQL 连不上也不是说账号密码错而是说在 dynamic-datasource 自己的路由表中没有拿到一个名字叫primary指定值的可路由数据源。1.2 从异常触发点反推配置要求这个异常并不是 Spring Boot 启动阶段必然抛出的很多时候要到第一次执行 SQL 时才会爆出来。拿源码来说异常是在DynamicRoutingDataSource.determineDataSource()这个方法里触发的。大致逻辑是这样的从当前线程上下文获取数据源 key如果 key 为空就使用 primary 作为默认 key如果 primary 也为空直接抛CannotFindDataSourceException如果 primary 有值但路由表里没有对应名字的数据源同样会走异常分支。所以触发条件实际上是两种一种是你根本没配置 primary另一种是你配置了 primary但路由表里的数据源名称和 primary 的值对不上。我曾经在一个项目里看到过这样的配置spring: datasource: dynamic: primary: master datasource: Master: url: jdbc:mysql://localhost:3306/demo乍一看没问题但数据源 key 写成了Master而 primary 是master大小写不一致。路由表里只有Master没有master组件自然找不到 primary。这类问题不是逻辑问题纯粹是命名规范没统一。2. 从现象到根因按这几个方向排查2.1 先确认配置文件里有没有spring.datasource.dynamic节点排查这个报错第一件事不是看代码而是先看你的application.yml或application.properties里到底有没有spring.datasource.dynamic这个配置节点。dynamic-datasource 这个 starter 的自动装配只会读取spring.datasource.dynamic下面的内容。如果你仍然在使用传统的spring: datasource: url: jdbc:mysql://localhost:3306/demo username: root password: root那 dynamic-datasource 是看不到任何数据源的。它的路由表是空的primary 自然也就无从谈起。正确的配置结构是这样spring: datasource: dynamic: primary: master strict: false datasource: master: url: jdbc:mysql://localhost:3306/demo username: root password: root driver-class-name: com.mysql.cj.jdbc.Driver slave: url: jdbc:mysql://localhost:3306/demo_slave username: root password: root driver-class-name: com.mysql.cj.jdbc.Driver注意datasource这个节点是在dynamic下面的不是直接在spring.datasource下面。YAML 缩进差一个空格整个配置就会失效。2.2 primary 的值和数据源 key 必须完全一致这个点看起来简单踩坑的人却不少。primary 支持三种写法直接写数据源 key 名称primary: master写${...}占位符从环境变量读取primary: ${DB_PRIMARY:master}不写 primary默认取数据源集合中第一个 key如果你选择不写 primary那么路由表里第一个数据源 key 会被当作主数据源。但这里有个隐藏前提路由表不能为空。只要datasource下面连一个数据源都没有即使你不写 primary它也会因找不到默认 key 而报错。我比较推荐项目里明确写 primary而不是依赖“第一个 key”这种隐式规则。因为 YAML 里 Map 的遍历顺序在不同版本下表现并不完全一致今天第一个可能是 master明天换一个 JDK 版本可能就变成 slave 了你的 primary 也就跟着变了。显式声明一次能避免很多莫名其妙的回归。2.3 strict 参数在这里是烟雾弹很多人搜到这个报错时会先去看strict参数。strict: true时如果你用DS指定了一个不存在的 key组件会报 “can not find datasource” 而不是回落到 primary。而strict: false时指定不存在的 key 会静默回落 primary。但这和 “can not find primary datasource” 是两码事。前者是找不到目标数据源后者是连兜底都没有。即使你设置了strict: false只要 primary 没配好或路由表为空一样会报你看到的这个异常。所以排查时不要把精力浪费在 strict 上先回去看路由表。2.4 自动装配被排除或依赖冲突也会引发同样问题还有一种情况配置文件完全没问题但项目里做了额外的数据源处理导致 dynamic-datasource 的自动装配压根没机会执行。最常见的两种在启动类上使用了exclude DataSourceAutoConfiguration.class然后又手动注入了其他DataSourceBean项目里同时引入了spring-boot-starter-jdbc和dynamic-datasource-spring-boot-starter配置里还保留了原生的spring.datasource.url。这两种情况下Spring 容器里可能存在多个数据源 Bean而 dynamic-datasource 的路由表组件可能没有正确初始化或者被另一个数据源 Bean 抢占了Primary的位置。结果就是运行到 SQL 路由时发现找不到一个“dynamic 管理的 primary”。3. 实操修复按步骤把 primary 找回来3.1 最常规的修复把 primary 和数据源名称对齐如果是配置问题最快的方式就是开一个干净的配置试一下。我一般会在排查时先随便配一个最小可运行的数据源把问题从“配置结构”和“业务代码”里剥离出来。spring: datasource: dynamic: primary: master strict: false datasource: master: url: jdbc:mysql://127.0.0.1:3306/test username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver配完之后启动项目直接访问一个最简单的 mapper 方法。如果不再报can not find primary datasource说明问题就是原来配置里的 key 名称、缩进或者层级写错了。接下来只需要把真实数据源逐个加回去每加一个就重启验证一下就能精准定位到是哪个数据源写得有问题。这里有个小技巧不要把不相关的数据源全部一下子配进去尤其是多个数据库地址、权限都不确定的时候。先只配 primary保证项目能站起来再逐步增加其他数据源。这样排错成本是最低的。3.2 用了 DS 却不生效时检查是否有事务包裹还有一种运行时才会触发的“找不到 primary”和配置完全无关。比如你在 Service 层写了这样的代码Transactional public void orderProcess() { orderMapper.insert(order); stockMapper.updateStock(stock); }然后你觉得既然 dynamic-datasource 支持多数据源那直接在方法上再加一个DS(slave)不就行了实际上Spring 默认的事务管理器会在事务开始时从数据源连接里获取 Connection后续整个事务内部都绑定在这条连接上。如果DS和Transactional同时出现哪怕你把DS放在方法上事务管理器也可能已经先把主数据源连接拿到了。这时候你期望切换到 slave 数据源但实际连接还是 primary 的甚至在某些极端情况下会直接导致路由失败抛出 “can not find primary datasource”。dynamic-datasource 对此也提供了自己的解法就是DSTransactional。它内部通过线程上下文和连接栈来管理多数据源事务允许在事务内切换数据源。但这个注解的使用限制很多不是无脑替代Transactional。我更建议的做法是事务边界尽量小不要在长事务里切换数据源如果必须切换把写操作和读操作拆分到不同 Service 方法里再在调用处通过DynamicDataSourceContextHolder.push()和poll()手动控制数据源。3.3 排除原生数据源自动配置后手动注册路由数据源如果项目里确实因为某种原因排除了DataSourceAutoConfiguration那么 dynamic-datasource 的自动配置可能不会被触发。这时候需要手动保证路由数据源被注册。一种简单的方式是在配置类里显式注册 dynamic-datasource 的核心 Bean。大致结构如下Configuration public class DynamicDataSourceConfig { Bean Primary public DataSource dataSource() { DynamicRoutingDataSource dataSource new DynamicRoutingDataSource(); // 手动设置数据源路由表 MapString, DataSource dataSourceMap new HashMap(); dataSourceMap.put(master, createDataSource(jdbc:mysql://127.0.0.1:3306/demo)); dataSource.setPrimary(master); dataSource.setStrict(false); dataSource.setDataSourceMap(dataSourceMap); return dataSource; } private DataSource createDataSource(String url) { // 使用你熟悉的连接池创建数据源 } }但这里有个前提你绕过了自动配置就需要自己处理连接池、配置绑定、监控等一堆东西。所以我个人不推荐一上来就这样做除非你已经确认是自动装配被某些框架拦截了。正常情况下用spring.datasource.dynamic自动装配就好不要手动去注册路由数据源。3.4 版本不匹配时的处理方式dynamic-datasource 的版本也是一个容易被忽略的变量。如果你用的是 3.5.x它基于 Spring Boot 2.x 的javax包如果你升级到 Spring Boot 3.x就必须配套使用 4.x 版本否则自动装配类可能因为类加载问题没有生效表现为各种数据源初始化异常其中也包括找不到 primary。最简单的处理方式就是用 Maven 或 Gradle 查看依赖树确认版本一致性mvn dependency:tree -Dincludescom.baomidou:dynamic-datasource-spring-boot-starter如果你发现项目里同时存在两个不同大版本的 dynamic-datasource那基本就是依赖冲突了。排除掉多余的依赖统一保留与 Spring Boot 匹配的版本即可。这里给一个简单的版本参考表Spring Boot 版本dynamic-datasource 推荐版本2.3.x ~ 2.7.x3.5.x3.0.x ~ 3.2.x4.1.x 及以上当然具体版本以官方文档为主但大版本方向一定要对齐不然排查半天配置问题最后发现是 starter 没自动加载就真的亏大了。4. 实测中容易踩的坑和排查技巧4.1 常见问题速查表根据我自己的项目经历也参考了很多同事遇到的类似问题这里整理成一个速查表格直接照着对号入座现象可能原因解决方式启动后执行第一条 SQL 才报错primary 未配置或路由表为空增加spring.datasource.dynamic.datasource配置YAML 配置看着没问题仍然报错缩进错误或配置键名拼写错误用编辑器格式化 YAML逐层确认dynamic层级primary 有值但找不到primary 和数据源 key 大小写不一致统一 key 命名强制全小写项目里自定义了 DataSource Bean动态路由数据源没有获得Primary去掉多余 Bean或给路由数据源加Primary方法上有 Transactional 时切换失败事务内数据源被事务管理器绑定拆分事务边界或使用DSTransactional升级 Spring Boot 后开始报错dynamic-datasource 版本不兼容升级 dynamic-datasource 到对应大版本测试类报错正常运行不报错测试环境没有加载完整配置文件在src/test/resources下补全 dynamic 配置日志里没有任何数据源加载记录自动配置未生效或配置节点读不到检查启动类 exclude检查依赖树这张表基本覆盖了我遇到过的 80% 的同类问题。剩下 20%大多集中在连接池初始化异常或数据库地址不可达但那通常会先报另一个异常不会被这个 primary 报错掩盖太深。4.2 开启 debug 日志直接看路由表内容排查这类问题最直接的手段是打开 dynamic-datasource 的 debug 日志。在配置文件里加上logging: level: com.baomidou.dynamic: debug启动后注意观察初始化日志里有没有类似这样的输出Load dynamic datasource: master Load dynamic datasource: slave如果日志里只打印了master没有slave那就说明slave的配置节点没有被加载。如果连master都没有说明整个 dynamic 配置都没有被读取这时候要去查自动装配和依赖版本。如果生产环境不方便开 debug也可以在本地写一个临时的ApplicationRunner把路由表里所有 key 打印出来Component public class DataSourceKeyPrinter implements ApplicationRunner { private final DynamicRoutingDataSource dynamicRoutingDataSource; public DataSourceKeyPrinter(DynamicRoutingDataSource dynamicRoutingDataSource) { this.dynamicRoutingDataSource dynamicRoutingDataSource; } Override public void run(ApplicationArguments args) { System.out.println(dynamicRoutingDataSource.getCurrentDataSources().keySet()); } }看到打印结果的那一刻你基本就能确定到底是配置没进去还是 key 对不上。4.3 别被“第一个数据源就是 primary”的惯性想法误导有些老项目里开发为了省事不写primary以为路由表里第一个就是主库。这个做法在大部分版本里确实能跑但不稳定。有一次我排查一个同事的问题他配置里确实没写 primary数据源顺序也是 master 在前。但项目启动后偶尔报 primary 找不到重启两次又好了。最后发现是无意中使用了不同的 JDK 版本Map 的遍历顺序发生了变化。虽然这种概率很低但一旦发生就是一种“玄学报错”。所以我在自己维护的项目里都强制要求显式配置primary并且在代码评审时也会特别关注这一点。别看只是多写一行配置它能把“偶发”的隐患变成“绝对稳定”的行为。4.4 测试环境的坑没有加载 application.yml却加载了 dynamic 自动配置还有一种容易被忽略的场景本地启动正常一跑单元测试就报 “can not find primary datasource”。这通常是因为测试环境的上下文加载方式和开发环境不一样。比如某个SpringBootTest类指定了properties内联配置但它没有把 dynamic 相关的配置传进来而测试类又扫描到了 mapper触发了数据源路由。解决方式很简单在src/test/resources下也放一份完整的application.yml或者用TestPropertySource单独指定测试配置。如果测试类不需要连数据库那就直接排除掉数据源相关自动配置SpringBootTest EnableAutoConfiguration(exclude {DataSourceAutoConfiguration.class})这样至少不会让测试跑到一半突然找不到 primary。5. 怎么让这套报错从此不再浪费你的时间这个报错本身不难解决难的是它出现的时机和位置都很“中性”。它不告诉你哪个配置错了也不告诉你哪个数据源没加载只说“找不到 primary”。很多人第一次遇到时会去搜索、复制粘贴、改配置来回折腾半天最后可能只是 YAML 缩进的问题。我的习惯是在新建一个使用 dynamic-datasource 的项目时先把最小配置跑通再写业务代码。也就是说不管你有几个数据源第一版配置里只放一个 master并且显式指定 primary。确认项目能启动、SQL 能跑通之后再逐个添加其他数据源。这样做的好处是一旦后面出现 and can not find primary datasource我基本能确定是新加的数据源配置导致了路由表问题不会把怀疑对象扩大到整个项目。另外如果项目里多人协作建议在 README 或架构文档里明确写清楚 primary 的命名规范和数据源 key 的命名规范。比如统一master、slave这种小写下划线风格不要混用大小写和驼峰。命名规范统一了这类问题能少一半。回到开头说的这个报错是一个典型的“配置路由”问题不是连接池问题也不是数据库问题。按着配置节点、key 名称、自动装配、事务边界这四个方向排查基本都能在十分钟内定位。希望这篇文档能让你少走几次弯路。

primary数据源配置排查：dynamic-datasource报错解决指南

相关推荐

Proteus电子秤仿真：HX711传感器建模与LCD1602驱动实战

Java日志框架底层原理与生产调优实战

基于EKF的路面附着系数估计与Simulink实现

更多资讯

PMP认证中的进度与成本管理实战技巧

后端开发必知：Java、Go、Python到底怎么选

从单体拆分为微服务后，我们的响应时间反而变长了？

PolarDB-X分布式JOIN性能实战：Broadcast与Shard策略选型指南

AutodL上Python虚拟环境实战：避坑root权限与加速pip安装

器官移植标准化差异分析与改进策略

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？