1. 项目概述：多数据源框架 dynamic-datasource 能解决什么问题？
在业务系统开发中，数据源管理一直是个让人头疼的问题。特别是当项目需要同时连接多个数据库时，传统的单数据源配置就显得力不从心了。dynamic-datasource 正是为解决这类问题而生的轻量级框架，它能让开发者在 Spring Boot 项目中像切换电视频道一样轻松切换不同的数据源。
我最早接触这个框架是在一个需要同时对接 MySQL 主从集群和 Oracle 报表数据库的金融项目中。当时团队尝试过手动管理多个数据源，结果发现事务管理、连接泄漏等问题层出不穷。dynamic-datasource 通过注解驱动的方式，完美解决了我们的痛点。现在它已经成为我技术栈中的标配组件，特别是在需要处理以下场景时：
- 读写分离架构中自动路由到主库或从库
- 多租户 SaaS 应用中每个租户独立的数据库
- 需要同时访问关系型数据库和 NoSQL 的混合架构
- 分库分表场景下的数据源动态切换
2. 核心设计解析：dynamic-datasource 如何工作？
2.1 整体架构设计
dynamic-datasource 的核心思想可以用"注册中心+路由策略"来概括。框架启动时会扫描所有配置的数据源，将它们注册到一个虚拟的数据源池中。这个池子实际上是对 Spring 原生 AbstractRoutingDataSource 的增强实现。
当执行数据库操作时，框架会根据当前线程上下文中的标识（通常是一个 lookup key）来决定使用哪个具体的数据源。整个过程对业务代码完全透明，开发者只需要通过简单的注解来指定数据源即可。
java复制// 典型的使用示例
@Service
public class UserService {
@DS("master") // 使用主库
public void addUser(User user) {
userMapper.insert(user);
}
@DS("slave") // 使用从库
public User getUser(Long id) {
return userMapper.selectById(id);
}
}
2.2 关键组件拆解
框架的核心组件可以分解为以下几个部分：
- 数据源加载器：负责解析 yml/properties 配置，初始化多个 DataSource 实例
- 动态路由数据源：继承自 AbstractRoutingDataSource，维护数据源映射关系
- 注解拦截器：通过 AOP 拦截 @DS 注解，设置当前线程的数据源标识
- 事务管理器：特殊处理的事务同步逻辑，确保事务内使用同一个数据源
- 健康检查器：定期检测各数据源的可用性
提示：框架默认采用线程本地变量(ThreadLocal)来保存数据源标识，这意味着如果在异步任务中切换数据源需要特别注意上下文传递问题。
3. 实战配置指南：从零搭建多数据源环境
3.1 基础配置示例
在 Spring Boot 项目中引入 dynamic-datasource 非常简单。以下是标准的 Maven 依赖和配置示例：
xml复制<!-- pom.xml 依赖 -->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>dynamic-datasource-spring-boot-starter</artifactId>
<version>3.5.1</version>
</dependency>
yaml复制# application.yml 配置
spring:
datasource:
dynamic:
primary: master # 设置默认数据源
datasource:
master:
url: jdbc:mysql://localhost:3306/master_db
username: root
password: 123456
driver-class-name: com.mysql.cj.jdbc.Driver
slave_1:
url: jdbc:mysql://localhost:3307/slave_db_1
username: root
password: 123456
driver-class-name: com.mysql.cj.jdbc.Driver
slave_2:
url: jdbc:mysql://localhost:3308/slave_db_2
username: root
password: 123456
driver-class-name: com.mysql.cj.jdbc.Driver
3.2 高级配置技巧
在实际项目中，我们通常需要更精细的控制。以下是一些实用配置项：
yaml复制spring:
datasource:
dynamic:
strict: true # 严格模式，未指定数据源时抛出异常
seata: true # 开启Seata分布式事务支持
hikari:
connection-timeout: 30000 # 统一设置连接池参数
max-lifetime: 1800000
druid:
initial-size: 5 # 如果使用Druid连接池的配置
aop:
order: -1 # AOP切面顺序，确保先于其他切面执行
对于需要动态增减数据源的场景，可以通过编程方式操作：
java复制@Autowired
private DynamicDataSourceProvider provider;
// 动态添加数据源
public void addDataSource(String name, DataSourceProperty property) {
DynamicRoutingDataSource ds = (DynamicRoutingDataSource) dataSource;
ds.addDataSource(name, provider.createDataSource(property));
}
// 移除数据源
public void removeDataSource(String name) {
DynamicRoutingDataSource ds = (DynamicRoutingDataSource) dataSource;
ds.removeDataSource(name);
}
4. 生产环境最佳实践
4.1 读写分离实现方案
在真实的读写分离场景中，我们通常需要更智能的路由策略。以下是结合负载均衡的实现示例：
java复制@Configuration
public class SlaveDataSourceSelector {
private static final Random random = new Random();
@DS("slave")
@Around("@annotation(slave)")
public Object around(ProceedingJoinPoint point) throws Throwable {
String[] slaves = {"slave_1", "slave_2", "slave_3"};
String selected = slaves[random.nextInt(slaves.length)];
DynamicDataSourceContextHolder.push(selected);
try {
return point.proceed();
} finally {
DynamicDataSourceContextHolder.poll();
}
}
}
4.2 多租户数据隔离方案
对于 SaaS 应用，每个租户可能需要独立的数据库。我们可以通过拦截器自动路由：
java复制public class TenantDataSourceInterceptor implements HandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
String tenantId = request.getHeader("X-Tenant-ID");
if (StringUtils.isNotBlank(tenantId)) {
String datasourceName = "tenant_" + tenantId;
if (dataSourceExists(datasourceName)) {
DynamicDataSourceContextHolder.push(datasourceName);
}
}
return true;
}
@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
DynamicDataSourceContextHolder.clear();
}
}
4.3 事务处理注意事项
多数据源环境下的事务管理需要特别注意：
- 本地事务：@Transactional 和 @DS 注解一起使用时，必须确保它们在同一个方法上，且 @DS 要在 @Transactional 之前执行
- 分布式事务：建议结合 Seata 等框架实现，配置时需要开启 seata.enable=true
- 事务传播：PROPAGATION_REQUIRES_NEW 会新建事务，但不会切换数据源
警告：绝对不要在事务方法内切换数据源，这会导致不可预知的结果。如果需要跨数据源操作，应该考虑使用分布式事务方案。
5. 性能优化与监控
5.1 连接池配置建议
不同连接池的推荐配置参数：
| 参数 | HikariCP 推荐值 | Druid 推荐值 | 说明 |
|---|---|---|---|
| 最小空闲连接 | 10 | 5 | 避免连接创建开销 |
| 最大连接数 | CPU核心数*2 + 有效磁盘数 | 20 | 根据实际负载调整 |
| 连接超时 | 30000ms | 30000ms | 网络状况差时适当增大 |
| 空闲超时 | 600000ms | 600000ms | 定期回收空闲连接 |
| 最大生命周期 | 1800000ms | 1800000ms | 定期重建连接避免陈旧 |
5.2 监控指标集成
通过 Spring Boot Actuator 暴露的监控端点：
yaml复制management:
endpoints:
web:
exposure:
include: health,info,datasource
endpoint:
health:
show-details: always
关键监控指标包括：
- 每个数据源的活跃连接数
- 连接等待时间
- 查询执行时间百分位
- 事务提交/回滚比率
6. 常见问题排查手册
6.1 典型错误与解决方案
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 找不到数据源异常 | 1. 注解值拼写错误 2. 数据源未正确初始化 |
1. 检查@DS("name")的name是否匹配配置 2. 查看启动日志确认数据源加载 |
| 事务不生效 | 1. 注解顺序错误 2. 传播行为设置不当 |
1. 确保@DS在@Transactional之前执行 2. 避免在事务内切换数据源 |
| 连接泄漏 | 1. 未正确关闭连接 2. 事务未正常结束 |
1. 检查finally块中是否调用了clear() 2. 配置连接池的泄漏检测参数 |
| 性能下降 | 1. 连接池配置不合理 2. 路由策略效率低 |
1. 调整连接池参数 2. 考虑缓存路由决策 |
6.2 调试技巧
- 开启调试日志：
yaml复制logging:
level:
com.baomidou.dynamic.datasource: DEBUG
- 在关键点打印当前数据源：
java复制log.debug("当前数据源: {}", DynamicDataSourceContextHolder.peek());
- 使用内存快照工具分析线程绑定的数据源标识
7. 扩展与定制开发
7.1 自定义数据源选择策略
默认的注解驱动方式可能不能满足所有场景。我们可以实现自己的选择逻辑：
java复制public class CustomDataSourceSelector extends AbstractDataSourceSelector {
@Override
public String determineDataSource(MethodInvocation invocation) {
// 根据方法名、参数等条件决定数据源
if (invocation.getMethod().getName().startsWith("query")) {
return "slave";
}
return "master";
}
}
// 注册自定义选择器
@Bean
public DataSourceAdvisor dataSourceAdvisor() {
DataSourceAdvisor advisor = new DataSourceAdvisor();
advisor.setDataSourceSelector(new CustomDataSourceSelector());
return advisor;
}
7.2 集成其他框架
与 MyBatis-Plus 的完美配合：
java复制@Configuration
public class MybatisPlusConfig {
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
// 分页插件
interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
// 动态数据源插件
interceptor.addInnerInterceptor(new DynamicDataSourceInnerInterceptor());
return interceptor;
}
}
与 Spring Cloud 的集成要点：
- 在 bootstrap.yml 中配置数据源
- 使用 @RefreshScope 实现配置热更新
- 通过 EnvironmentChangeEvent 监听配置变化
8. 版本升级与迁移指南
从 2.x 升级到 3.x 的主要变化：
- 包路径从 com.baomidou.dynamic 改为 com.baomidou.dynamic.datasource
- 移除了对 spring-boot-starter-jdbc 的自动依赖
- 默认连接池改为 HikariCP
- 注解处理器执行顺序调整
迁移步骤：
- 更新依赖版本
- 检查自定义的 AbstractRoutingDataSource 实现
- 测试事务边界条件下的行为
- 验证异步任务中的数据源传递
我在实际升级过程中发现，最大的兼容性问题出现在自定义事务管理器的情况下。建议先在一个测试环境充分验证，特别是检查以下场景：
- 嵌套事务传播行为
- 异步方法调用链
- 定时任务中的数据源切换
9. 替代方案对比
与其他多数据源方案的比较：
| 特性 | dynamic-datasource | AbstractRoutingDataSource | ShardingSphere |
|---|---|---|---|
| 学习成本 | 低 | 中 | 高 |
| 功能丰富度 | 中 | 低 | 高 |
| 性能开销 | 低 | 低 | 中 |
| 事务支持 | 本地事务 | 本地事务 | 分布式事务 |
| 适合场景 | 简单多数据源 | 完全自定义场景 | 分库分表 |
选择建议：
- 10个以下数据源，简单路由策略 → dynamic-datasource
- 需要高度定制路由逻辑 → AbstractRoutingDataSource
- 分库分表+分布式事务 → ShardingSphere
10. 源码解析与贡献指南
框架的核心逻辑集中在几个关键类：
- DynamicDataSourceCreator - 数据源创建策略
- DynamicDataSourceAnnotationInterceptor - 注解拦截器
- DynamicRoutingDataSource - 路由数据源实现
- DataSourceClassResolver - 注解解析器
如果想深入了解工作原理，建议从 DynamicDataSourceAutoConfiguration 开始跟踪初始化过程。对于想要贡献代码的开发者，可以从以下几个方面入手：
- 增加更多连接池的支持（如 Tomcat JDBC）
- 完善测试覆盖率
- 编写更丰富的使用示例
- 优化文档结构
调试源码时的一个小技巧：设置断点在 DynamicDataSourceContextHolder 的 push/poll 方法，可以清晰看到整个调用栈中的数据源切换过程。