SpringBoot多租户实战:用dynamic-datasource-spring-boot-starter 3.5.1构建企业级动态数据源架构
如果你正在为一个SaaS平台或者一个需要服务多个独立客户(租户)的内部系统发愁,数据隔离肯定是绕不开的核心难题。每个租户的数据必须物理或逻辑上分开,但代码又希望是同一套,这种矛盾在项目初期可能还能用一些“土办法”对付,但随着租户数量增长,维护成本会指数级上升。我经历过不止一个项目,从简单的数据库前缀区分,到后来不得不重构为更彻底的隔离方案,踩过的坑让我深刻意识到,一个清晰、可维护的多租户数据源架构是多么重要。
今天我们不谈那些过于理论化的设计模式,直接聚焦于一个在SpringBoot生态中非常流行的解决方案:dynamic-datasource-spring-boot-starter。这个由苞米豆团队维护的组件,以其轻量、非侵入和强大的动态管理能力,成为了许多中小型项目实现多租户数据隔离的首选。我们将基于最新的3.5.1版本,从零开始,搭建一个生产可用的多租户系统。重点不仅仅是配置怎么写,而是如何将数据源动态切换与你的业务登录流程、连接池管理、事务控制无缝集成,解决那些文档里不会写,但实际开发中一定会遇到的“高频痛点”。
1. 架构核心:理解多租户与动态数据源
在深入代码之前,我们必须对要解决的问题和采用的方案有一个清晰的蓝图。多租户(Multi-Tenancy)架构,简单说就是一套应用实例能够同时为多个相互隔离的客户(租户)提供服务。数据隔离是其核心,通常有三种实现方式:
- 独立数据库:每个租户拥有自己独立的数据库实例。隔离性最好,安全性最高,但成本也最大。
- 共享数据库,独立Schema:所有租户共享同一个数据库实例,但每个租户有自己的一套表(Schema)。在MySQL中,Schema基本等同于Database。
- 共享数据库,共享Schema:所有租户的数据都存放在同一套表中,通过一个
tenant_id字段来区分。结构最简单,但数据隔离和查询复杂度较高。
我们即将实现的,是第二种方式:共享数据库实例,但每个租户有独立的数据库(Schema)。dynamic-datasource 在这里扮演的角色,就是根据当前请求的租户身份,动态地将数据库连接指向对应的租户数据库。
它的工作原理可以概括为下图所示的流程:
sequenceDiagram
participant C as 客户端/租户
participant I as 拦截器
participant H as DynamicDataSourceContextHolder
participant DRDS as DynamicRoutingDataSource
participant D as 目标数据源
participant DB as 租户数据库
C->>I: 发起请求(携带租户标识)
I->>H: 解析标识,将租户Key压入线程上下文
H->>DRDS: 当前线程需使用租户Key对应的数据源
DRDS->>DRDS: 根据Key查找/创建数据源
DRDS->>D: 获取目标数据源连接
D->>DB: 执行SQL操作
DB-->>D: 返回数据
D-->>DRDS: 返回连接
DRDS-->>H: 完成操作
H-->>I: 请求处理完毕
I->>H: 清理线程上下文中的租户Key
I-->>C: 返回响应
这个流程的核心在于 DynamicDataSourceContextHolder 这个类。它利用 ThreadLocal 为每个请求线程绑定了一个数据源标识(Key)。当程序执行数据库操作时,DynamicRoutingDataSource(动态路由数据源)会向它询问:“当前线程要用哪个数据源?” 然后它就像个路由器一样,把连接请求导向正确的目标。
这种设计的好处是对业务代码几乎无侵入。你的Service层、Mapper层完全不用关心当前操作的是哪个租户的数据,它们只需要像在单数据源环境下一样编写SQL即可。数据源的切换在更上层的拦截器或过滤器中透明完成。
2. 环境搭建与基础配置
理论清晰后,我们开始动手。首先创建一个标准的SpringBoot项目,这里我推荐使用Spring Initializr,选择必要的依赖:Spring Web, Spring Data JPA (或MyBatis-Plus),以及MySQL Driver。
2.1 引入核心依赖
在 pom.xml 中,添加 dynamic-datasource-spring-boot-starter 的依赖。强烈建议明确指定版本号,以避免后续因版本自动升级带来的不兼容问题。
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>dynamic-datasource-spring-boot-starter</artifactId>
<version>3.5.1</version>
</dependency>
如果你计划使用Druid连接池(这也是生产环境的常见选择),需要排除SpringBoot的默认HikariCP自动配置,并引入Druid的starter。
<!-- Druid 连接池 -->
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>druid-spring-boot-starter</artifactId>
<version>1.2.16</version> <!-- 请使用最新稳定版 -->
</dependency>
注意:
dynamic-datasource支持多种连接池,它会按照druid > hikaricp > beecp > dbcp > spring basic的顺序自动检测并创建。显式引入Druid依赖后,它会优先使用Druid。
2.2 配置数据源信息
接下来是 application.yml 的配置。这里我们需要定义一个主数据源,它用于存储系统本身的管理信息,例如用户账号、租户信息、以及各个租户的数据源配置。这个库是系统启动和管理的基石。
spring:
datasource:
dynamic:
primary: master # 默认数据源名称,项目启动时会使用这个数据源
strict: false # 严格模式,建议false。如果为true,切换到一个不存在的数据源会抛异常;为false则回退到primary数据源。
datasource:
master: # 主数据源,用于管理系统元数据
driver-class-name: com.mysql.cj.jdbc.Driver
url: jdbc:mysql://localhost:3306/management_db?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
username: root
password: your_password
# 如果整合Druid,需要排除默认的Druid自动配置,由dynamic-datasource接管
autoconfigure:
exclude: com.alibaba.druid.spring.boot.autoconfigure.DruidDataSourceAutoConfigure
对于Druid连接池的调优参数,我建议不要一开始就堆砌所有配置。可以先使用一组经过验证的、适用于中小并发场景的基础配置,后续根据监控再调整。
# 接在上面的 dynamic 配置之后
druid:
initial-size: 5
min-idle: 5
max-active: 20
max-wait: 60000
test-on-borrow: false
test-on-return: false
test-while-idle: true
validation-query: SELECT 1
time-between-eviction-runs-millis: 60000
min-evictable-idle-time-millis: 300000
提示:
validation-query对于MySQL通常是SELECT 1,对于Oracle可能是SELECT 1 FROM DUAL。确保它简单高效,仅用于检测连接是否存活。
2.3 设计元数据表
我们的系统需要一个“总指挥部”来记录所有租户的数据源信息。我们在主库(management_db)中创建一张表 sys_tenant_datasource。
CREATE TABLE `sys_tenant_datasource` (
`id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
`tenant_id` varchar(64) NOT NULL COMMENT '租户唯一标识',
`tenant_name` varchar(128) DEFAULT NULL COMMENT '租户名称',
`datasource_name` varchar(64) NOT NULL COMMENT '动态数据源名称(对应poolName)',
`driver_class_name` varchar(256) DEFAULT 'com.mysql.cj.jdbc.Driver' COMMENT 'JDBC驱动类',
`url` varchar(512) NOT NULL COMMENT '数据库连接URL',
`username` varchar(128) NOT NULL COMMENT '数据库用户名',
`password` varchar(256) NOT NULL COMMENT '数据库密码',
`status` tinyint(1) DEFAULT '1' COMMENT '状态(1启用,0停用)',
`create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_tenant_id` (`tenant_id`),
UNIQUE KEY `uk_datasource_name` (`datasource_name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='租户数据源配置表';
对应的JPA实体类(如果使用MyBatis,则是Mapper和实体类)如下:
import javax.persistence.*;
import java.time.LocalDateTime;
@Entity
@Table(name = "sys_tenant_datasource")
public class TenantDataSource {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(name = "tenant_id", nullable = false, unique = true, length = 64)
private String tenantId;
private String tenantName;
@Column(name = "datasource_name", nullable = false, unique = true, length = 64)
private String datasourceName;
private String driverClassName = "com.mysql.cj.jdbc.Driver";
@Column(nullable = false, length = 512)
private String url;
@Column(nullable = false, length = 128)
private String username;
@Column(nullable = false, length = 256)
private String password;
private Boolean status = true;
private LocalDateTime createTime;
private LocalDateTime updateTime;
// 省略 getter/setter 和构造方法
}
这张表是动态数据源的“注册中心”。系统启动时,以及后续新增租户时,都会根据这里的配置来动态创建或移除数据源。
3. 核心实现:动态数据源的生命周期管理
配置好基础环境后,我们进入核心环节:如何让数据源“动”起来。这包括启动时加载、运行时增删改查以及最重要的——按需切换。
3.1 启动时加载所有租户数据源
项目启动时,我们需要从 sys_tenant_datasource 表中读取所有已启用的租户数据源配置,并将它们注册到 DynamicRoutingDataSource 中。这通过一个 @PostConstruct 方法来实现。
import com.baomidou.dynamic.datasource.DynamicRoutingDataSource;
import com.baomidou.dynamic.datasource.creator.DataSourceCreator;
import com.baomidou.dynamic.datasource.spring.boot.autoconfigure.DataSourceProperty;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;
import javax.sql.DataSource;
import java.util.List;
@Slf4j
@Component
@RequiredArgsConstructor
public class TenantDataSourceLoader implements CommandLineRunner {
private final DataSource dataSource; // 这里注入的是DynamicRoutingDataSource
private final DataSourceCreator dataSourceCreator;
private final TenantDataSourceRepository tenantDataSourceRepo; // 你的Repository或Service
@Override
public void run(String... args) {
log.info("开始初始化租户数据源...");
List<TenantDataSource> activeDataSources = tenantDataSourceRepo.findByStatus(true);
DynamicRoutingDataSource ds = (DynamicRoutingDataSource) dataSource;
for (TenantDataSource config : activeDataSources) {
try {
// 1. 构建数据源属性
DataSourceProperty property = new DataSourceProperty();
property.setPoolName(config.getDatasourceName()); // 关键:poolName
property.setDriverClassName(config.getDriverClassName());
property.setUrl(config.getUrl());
property.setUsername(config.getUsername());
property.setPassword(config.getPassword());
// 可以在这里设置连接池特定参数,如Druid参数
// property.setDruid(...);
// 2. 创建数据源并注册
DataSource tenantDataSource = dataSourceCreator.createDataSource(property);
ds.addDataSource(property.getPoolName(), tenantDataSource);
log.info("成功加载租户数据源: {} -> {}", config.getTenantName(), config.getDatasourceName());
} catch (Exception e) {
log.error("加载租户数据源失败: {}", config.getDatasourceName(), e);
// 根据策略决定是否阻断启动:throw new RuntimeException("数据源加载失败", e);
}
}
log.info("租户数据源初始化完成,共加载 {} 个数据源。", activeDataSources.size());
}
}
使用 CommandLineRunner 或 ApplicationRunner 接口,可以确保在SpringBoot应用完全启动后执行初始化逻辑,比 @PostConstruct 在某些场景下更可靠。
3.2 运行时管理数据源
租户可能会动态增加、或者其数据库连接信息可能变更。我们需要提供API来管理这些数据源。
添加数据源:当新租户注册时,除了在业务表记录租户信息,还需要将其数据源配置入库并动态添加到运行时。
@RestController
@RequestMapping("/admin/datasource")
@RequiredArgsConstructor
public class TenantDataSourceController {
private final DynamicRoutingDataSource dynamicRoutingDataSource;
private final DataSourceCreator dataSourceCreator;
private final TenantDataSourceService dataSourceService;
@PostMapping
public ApiResponse<String> addDataSource(@RequestBody @Valid TenantDataSourceDTO dto) {
// 1. 持久化到数据库
TenantDataSource savedConfig = dataSourceService.save(dto);
// 2. 动态添加到当前运行的数据源集合
DataSourceProperty property = new DataSourceProperty();
BeanUtils.copyProperties(savedConfig, property);
property.setPoolName(savedConfig.getDatasourceName());
DataSource newDataSource = dataSourceCreator.createDataSource(property);
dynamicRoutingDataSource.addDataSource(property.getPoolName(), newDataSource);
return ApiResponse.success("数据源添加成功");
}
}
移除数据源:当租户注销或停用时,需要从运行时移除并关闭其连接池。
@DeleteMapping("/{datasourceName}")
public ApiResponse<String> removeDataSource(@PathVariable String datasourceName) {
// 1. 检查是否有业务正在使用此数据源(可根据实际情况实现)
// 2. 从动态数据源中移除
dynamicRoutingDataSource.removeDataSource(datasourceName);
// 3. 更新数据库状态(如设为停用)
dataSourceService.disableDataSource(datasourceName);
return ApiResponse.success("数据源移除成功");
}
注意:
removeDataSource方法会关闭该数据源对应的连接池。务必确保在执行此操作时,没有正在进行的事务或数据库操作使用该数据源,否则可能导致连接泄漏或错误。
3.3 基于拦截器的自动切换
这是实现多租户透明化的关键。我们需要一个拦截器,在请求进入Controller之前,根据当前请求的租户标识,自动切换到对应的数据源。
首先,我们需要一种方式从请求中获取租户标识。常见做法有:
- 子域名:
tenant1.your-app.com - 请求头:
X-Tenant-Id: tenant_001 - 请求路径:
/api/tenant/tenant_001/users - JWT Token:将租户ID编码在用户认证令牌中。
这里以请求头 X-Tenant-Id 为例,实现一个拦截器。
import com.baomidou.dynamic.datasource.toolkit.DynamicDataSourceContextHolder;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.Optional;
@Slf4j
@Component
public class TenantDataSourceInterceptor implements HandlerInterceptor {
private static final String TENANT_HEADER = "X-Tenant-Id";
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
// 1. 从请求头中提取租户ID
String tenantId = Optional.ofNullable(request.getHeader(TENANT_HEADER))
.orElse("default"); // 或者抛异常,根据业务
// 2. 根据租户ID,查找或计算出对应的数据源名称 (datasourceName)
// 这里假设租户ID直接作为数据源名称,或者通过一个简单的服务转换
String datasourceKey = resolveDataSourceKey(tenantId);
// 3. 将数据源Key设置到当前线程上下文中
if (datasourceKey != null) {
DynamicDataSourceContextHolder.push(datasourceKey);
log.debug("当前请求 [{}] 已切换到数据源: {}", request.getRequestURI(), datasourceKey);
} else {
// 如果找不到对应数据源,可以回退到主数据源或抛出异常
DynamicDataSourceContextHolder.push("master");
log.warn("未找到租户 [{}] 对应的数据源,已切换至主数据源。", tenantId);
}
return true;
}
@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
// 请求完成后,务必清理当前线程的数据源上下文,防止内存泄漏和上下文污染
DynamicDataSourceContextHolder.clear();
log.debug("清理当前线程数据源上下文。");
}
private String resolveDataSourceKey(String tenantId) {
// 这里可以实现更复杂的逻辑,例如从缓存中查询租户-数据源映射
// 简单场景下,可以直接用 tenantId 作为 key,前提是你的数据源名称就是tenantId
return "ds_" + tenantId; // 例如: ds_tenant_001
}
}
然后,将这个拦截器注册到Spring MVC中。
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class WebConfig implements WebMvcConfigurer {
private final TenantDataSourceInterceptor tenantDataSourceInterceptor;
public WebConfig(TenantDataSourceInterceptor tenantDataSourceInterceptor) {
this.tenantDataSourceInterceptor = tenantDataSourceInterceptor;
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(tenantDataSourceInterceptor)
.addPathPatterns("/api/**") // 拦截所有API请求
.excludePathPatterns("/api/auth/**", "/admin/**"); // 排除登录、管理等无需租户隔离的接口
}
}
这样,所有匹配 /api/** 的请求在进入业务逻辑前,都会自动根据 X-Tenant-Id 请求头切换到正确的租户数据库。业务代码无需任何修改。
4. 进阶议题与生产环境踩坑指南
基础功能跑通只是第一步,要真正用于生产,还必须处理好以下几个棘手问题。
4.1 事务管理的挑战与解决方案
在动态数据源环境下,事务管理变得复杂。Spring的 @Transactional 注解在方法开始时,会从 DataSourceTransactionManager 获取一个连接并绑定到当前线程。如果我们的数据源切换发生在 @Transactional 注解生效之后(例如,在Service方法内部调用 DynamicDataSourceContextHolder.push()),那么事务将仍然使用最初的数据源,导致数据错乱。
解决方案是:确保数据源切换发生在事务开启之前。 我们的拦截器(preHandle)在Controller之前执行,而Spring的声明式事务通常通过AOP在Service方法调用前开启,这两者的顺序至关重要。默认情况下,拦截器的顺序可能早于事务AOP。为了确保万无一失,我们可以:
- 明确指定顺序:通过
@Order注解或实现Ordered接口,确保拦截器的优先级高于事务管理器。 - 使用Spring的
TransactionSynchronizationManager进行手动资源管理(不推荐,复杂度高)。 - 最稳妥的方案:将租户标识的解析和数据源Key的确定,提前到过滤器(Filter) 或 Spring Security 认证成功之后的环节,因为它们执行顺序更靠前。
一个常见的实践是结合Spring Security,在用户认证成功后,将租户信息存入 SecurityContext 或自定义的线程上下文,然后在事务AOP之前,通过一个BeanPostProcessor或自定义的 AbstractRoutingDataSource 实现(虽然我们用dynamic-datasource,但原理相通)来根据上下文设置数据源。
4.2 连接池配置优化
每个动态数据源都有自己的连接池。如果租户数量很多(比如上百个),每个连接池都保持 minIdle=5,就会产生数百个闲置连接,对数据库造成压力。
优化策略:
- 按需创建/销毁:对于不活跃的租户,可以考虑在拦截器中判断,如果长时间没有请求,则动态移除其数据源(
removeDataSource)。下次请求时再懒加载。这需要一套租户活跃度监控和懒加载机制。 - 差异化配置:为不同级别的租户(如VIP和普通)配置不同的连接池参数。可以在
sys_tenant_datasource表中增加字段存储连接池配置(JSON格式),在DataSourceCreator.createDataSource()时传入。 - 共享连接池探索:极端情况下,可以考虑让多个小租户共享一个物理数据库,但使用不同的Schema。这时可以尝试配置一个较大的公共连接池,然后在执行SQL前动态修改连接的Schema(如执行
USE tenant_schema;)。但这需要修改SQL执行层面,dynamic-datasource默认不直接支持,可能需要自定义扩展。
4.3 多租户下的缓存与上下文隔离
数据源隔离了,但缓存呢?如果你的应用使用了Redis或本地缓存(如Caffeine),必须确保缓存Key也包含租户标识,否则会发生租户间数据泄露。
// 错误的缓存Key,会导致租户A看到租户B的数据
String cacheKey = "user:" + userId;
// 正确的缓存Key
String tenantAwareCacheKey = tenantId + ":user:" + userId;
同样,任何使用 ThreadLocal 存储的上下文信息,在异步任务(如 @Async、消息监听)中都会丢失。你需要使用 TaskDecorator 或 TransmittableThreadLocal(如果使用线程池)来传递租户上下文。
import org.springframework.core.task.TaskDecorator;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class AsyncConfig {
@Bean("tenantAwareTaskExecutor")
public ThreadPoolTaskExecutor taskExecutor() {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
// ... 配置核心线程数等参数
executor.setTaskDecorator(new TenantAwareTaskDecorator());
executor.initialize();
return executor;
}
static class TenantAwareTaskDecorator implements TaskDecorator {
@Override
public Runnable decorate(Runnable runnable) {
// 获取当前线程的租户上下文
String currentTenantId = TenantContextHolder.getCurrentTenantId();
return () -> {
try {
// 在新线程中设置租户上下文
TenantContextHolder.setTenantId(currentTenantId);
runnable.run();
} finally {
TenantContextHolder.clear();
}
};
}
}
}
4.4 监控、日志与问题排查
当系统有几十个动态数据源在运行时,监控和日志变得至关重要。
- 连接池监控:如果使用Druid,可以为每个动态数据源开启监控。但注意,每个数据源的监控StatViewServlet和WebStatFilter需要独立配置和管理,避免冲突。
dynamic-datasource对Druid监控的支持需要仔细查阅其文档或源码。 - 统一日志:在所有数据库操作相关的日志中,打印当前数据源Key。你可以通过自定义MyBatis拦截器或使用
dynamic-datasource自带的SLF4J日志功能来实现。 - 健康检查:Spring Boot Actuator的
/health端点默认只会检查主数据源。你需要自定义一个HealthIndicator来检查所有动态数据源的健康状态。
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
import com.baomidou.dynamic.datasource.DynamicRoutingDataSource;
import javax.sql.DataSource;
import java.sql.Connection;
import java.util.Map;
@Component
public class DynamicDataSourceHealthIndicator implements HealthIndicator {
private final DynamicRoutingDataSource dynamicRoutingDataSource;
public DynamicDataSourceHealthIndicator(DataSource dataSource) {
this.dynamicRoutingDataSource = (DynamicRoutingDataSource) dataSource;
}
@Override
public Health health() {
Map<String, DataSource> dataSources = dynamicRoutingDataSource.getDataSources();
Map<String, Health> details = new LinkedHashMap<>();
boolean allUp = true;
for (Map.Entry<String, DataSource> entry : dataSources.entrySet()) {
String dsName = entry.getKey();
try (Connection conn = entry.getValue().getConnection()) {
if (conn.isValid(2)) { // 2秒超时
details.put(dsName, Health.up().build());
} else {
details.put(dsName, Health.down().withDetail("error", "Connection validation failed").build());
allUp = false;
}
} catch (Exception e) {
details.put(dsName, Health.down(e).build());
allUp = false;
}
}
Health.Builder builder = allUp ? Health.up() : Health.down();
return builder.withDetails(details).build();
}
}
这套方案从实战中来,也经过了我们多个内部项目的检验。它最大的优势在于平衡了隔离性与开发复杂度,用一套相对清晰的架构,解决了多租户数据访问的核心矛盾。当然,没有银弹,你需要根据自己业务的规模、租户的增长模式以及运维能力,对上述的每一个环节进行细化和调整。比如,当租户量达到数千时,启动时全量加载数据源可能不再合适,你可能需要引入更复杂的懒加载和缓存淘汰机制。但无论如何,理解并掌握 dynamic-datasource 提供的这套动态路由机制,是你构建现代SaaS应用后端架构的重要一步。
365



被折叠的 条评论
为什么被折叠?



