Spring Boot 3.x 使用多数据源动态切换为何必须用 dynamic-datasource-spring-boot3-starter

🚀 Spring Boot 3.x 使用多数据源动态切换为何必须用 dynamic-datasource-spring-boot3-starter？

📝 一、问题描述

升级 Spring Boot 到 3.x 后，很多使用了 dynamic-datasource-spring-boot-starter（原版）项目启动失败，出现如下错误：

Failed to configure a DataSource: 'url' attribute is not specified and no embedded datasource could be configured.
Reason: Failed to determine a suitable driver class

导致项目无法正常启动。

🔍 二、错误原因分析

1️⃣ Spring Boot 3.x 的变化

Spring Boot 3 基于 Jakarta EE 9 规范，底层依赖从 javax.* 包迁移到了 jakarta.* 包：

• 原先使用 javax.sql.DataSource 等相关类被迁移为 jakarta.sql.DataSource。
• Spring Framework、Spring Boot、相关依赖均完成了向 jakarta 的迁移。

2️⃣ dynamic-datasource-spring-boot-starter 不兼容问题

• 该 starter 的 4.x 版本主要支持 Spring Boot 2.x，依赖 javax 包。
• 在 Spring Boot 3.x（Spring Framework 6）环境中，由于 javax 包被移除，导致其内部涉及数据源代理、路由等类无法正确装配。
• 这会导致 Spring Boot 在自动配置时找不到合适的 DataSource 驱动和配置，从而抛出“url attribute is not specified”错误。

✅ 三、解决方案：使用 dynamic-datasource-spring-boot3-starter

为了适配 Spring Boot 3.x，作者团队发布了专门的 starter：

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>dynamic-datasource-spring-boot3-starter</artifactId>
    <version>4.3.0</version>
</dependency>

特点：

• 完全基于 Jakarta EE 9 规范，兼容 Spring Boot 3.x 和 Spring Framework 6。
• 重写了依赖注入和数据源路由相关代码，支持最新的数据源接口。
• 保持原有 API 和配置兼容，升级门槛低。

🛠 四、如何切换到 Spring Boot 3.x 的动态数据源

1. 修改依赖

将旧版本：

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>dynamic-datasource-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

替换为：

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>dynamic-datasource-spring-boot3-starter</artifactId>
    <version>4.3.0</version>
</dependency>

2. 保持配置文件不变

application.yml 中数据源配置可保持一致：

spring:
  datasource:
    dynamic:
      primary: master
      datasource:
        master:
          url: jdbc:mysql://localhost:3306/test?useSSL=false&serverTimezone=UTC
          username: root
          password: 123456
          driver-class-name: com.mysql.cj.jdbc.Driver
        slave:
          url: jdbc:mysql://localhost:3307/test?useSSL=false&serverTimezone=UTC
          username: root
          password: 123456
          driver-class-name: com.mysql.cj.jdbc.Driver

3. 其他代码基本无需修改

🔎 五、源码分析与官方说明

1. 官方源码仓库

dynamic-datasource-spring-boot-starter 项目托管在 GitHub：

👉 https://github.com/baomidou/dynamic-datasource-spring-boot-starter

2. 版本支持与分支结构

• master 分支 主要支持 Spring Boot 2.x，基于 javax.* 依赖。
• springboot3 分支 专门适配 Spring Boot 3.x，依赖迁移至 jakarta.*，修复包名变更导致的兼容性问题。

3. 官方 README 中的升级提示

在 README 中明确提到：

For Spring Boot 3.x users, please use the dynamic-datasource-spring-boot3-starter artifact, which is fully compatible with Jakarta EE 9 and Spring Framework 6.

4. 依赖差异对比

5. 关键代码变化示例

// Spring Boot 2.x 版示例，依赖 javax.sql.DataSource
import javax.sql.DataSource;

// Spring Boot 3.x 版示例，依赖 jakarta.sql.DataSource
import jakarta.sql.DataSource;

由于底层包名变更，若使用老版本 starter 在 Spring Boot 3.x 环境中会导致自动装配失败。

🧾 六、总结

升级 Spring Boot 3.x 后，一定要切换到 -spring-boot3-starter 版本，否则会因为包兼容性导致启动失败。

🔗 七、参考链接

• dynamic-datasource 官方 GitHub
• Spring Boot 3 升级指南
• Jakarta EE 9 包迁移说明

⭐ 如果觉得本文对你有帮助，欢迎点赞和收藏！