MyBatis多数据源全解析：从静态到动态，实战踩坑指南

于 2025-07-14 21:26:40 发布
阅读量747 收藏 20
点赞数 20
CC 4.0 BY-SA版权
文章标签： mybatis 多数据源 springboot 事务
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_42148384/article/details/149339542

引言

在Java企业级开发中，数据库操作可以说是最基础也最核心的需求之一。早期我们习惯用单数据源“打天下”——一个应用连一个数据库，写操作、读操作全走同一个连接。但随着业务规模扩大，单数据源的局限性逐渐暴露：主库压力过大却无法分流查询、多租户数据混存导致维护困难、跨库操作事务难以保证……这时候，​MyBatis多数据源能力就成了破解困局的关键。

今天这篇文章，笔者将结合企业级开发的实际需求，从为什么需要多数据源、静态/动态配置实战、事务避坑指南到性能优化技巧，带你全面掌握这一核心技能。无论你是刚接触多数据源的新手，还是想优化现有架构的开发者，这篇都能帮你理清思路、避开陷阱，真正把多数据源用对、用好。

一、为什么需要多数据源？常见场景有哪些？

在实际开发中，单数据源往往无法满足复杂业务需求。我总结了3个最常用的场景，看看你有没有遇到过：

1. 主从读写分离

这是最常见的场景！主库负责写（增删改），从库负责读（查询）。主库写操作后立即同步到从库，但可能会有延迟。比如电商大促时，主库压力大，通过读写分离可以把查询压力分散到从库，提升系统吞吐量。

2. 多租户隔离（SaaS系统）

如果你做过SaaS系统，肯定见过“一个租户一个库”的设计。比如为公司A、B、C分别分配独立数据库，通过租户ID动态切换数据源，避免数据混在一起。

3. 异构数据库访问

有时候系统需要同时操作关系型数据库（如MySQL）和非关系型数据库（如Redis、MongoDB）。虽然MyBatis主要操作关系型数据库，但配合其他框架（如Spring Data Redis）也能实现多数据源访问。

二、静态多数据源：固定数据源的场景

如果你的业务中数据源数量固定（比如主库+1个从库），静态多数据源是最直接的选择。它的核心是为每个数据源创建独立的DataSource、SqlSessionFactory和事务管理器。

步骤1：环境准备（Spring Boot项目）

首先，在pom.xml中添加依赖。注意：MyBatis核心库、数据库驱动（如MySQL）、连接池（推荐HikariCP）是必选的。

<!-- MyBatis 核心 -->
<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>2.3.1</version>
</dependency>

<!-- MySQL 驱动 -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

<!-- HikariCP 连接池（Spring Boot默认） -->
<dependency>
    <groupId>com.zaxxer</groupId>
    <artifactId>HikariCP</artifactId>
</dependency>

步骤2：配置多数据源参数（application.yml）

在配置文件中定义主库和从库的连接信息。注意：每个数据源的jdbc-url、username、password都要单独配置！

spring:
  datasource:
    # 主库配置（写操作）
    master:
      jdbc-url: jdbc:mysql://localhost:3306/master_db?useSSL=false&serverTimezone=Asia/Shanghai
      username: root
      password: 123456
      driver-class-name: com.mysql.cj.jdbc.Driver
      hikari:
        maximum-pool-size: 20  # 最大连接数
        connection-timeout: 30000  # 连接超时时间（毫秒）
    # 从库配置（读操作）
    slave:
      jdbc-url: jdbc:mysql://localhost:3307/slave_db?useSSL=false&serverTimezone=Asia/Shanghai
      username: root
      password: 123456
      driver-class-name: com.mysql.cj.jdbc.Driver
      hikari:
        maximum-pool-size: 15  # 从库压力小，连接数可以少点

步骤3：定义数据源Bean

通过@ConfigurationProperties绑定配置，并创建两个独立的DataSource Bean。这里要注意给每个Bean起不同的名字（如masterDataSource、slaveDataSource），后续要用到。

@Configuration
public class DataSourceConfig {

    // 主库数据源（@Primary表示默认数据源，可选）
    @Bean("masterDataSource")
    @ConfigurationProperties(prefix = "spring.datasource.master")
    public DataSource masterDataSource() {
        return DataSourceBuilder.create().build();
    }

    // 从库数据源
    @Bean("slaveDataSource")
    @ConfigurationProperties(prefix = "spring.datasource.slave")
    public DataSource slaveDataSource() {
        return DataSourceBuilder.create().build();
    }
}

步骤4：配置SqlSessionFactory和事务管理器

每个数据源需要对应的SqlSessionFactory（生成SqlSession）和事务管理器（控制本地事务）。这里要注意：

  • SqlSessionFactory需要指定Mapper XML的路径（避免不同数据源的Mapper冲突）。
  • 事务管理器必须和SqlSessionFactory一一对应。
@Configuration
public class SqlSessionFactoryConfig {

    // 主库 SqlSessionFactory
    @Bean("masterSqlSessionFactory")
    public SqlSessionFactory masterSqlSessionFactory(
            @Qualifier("masterDataSource") DataSource dataSource) throws Exception {
        SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
        sessionFactory.setDataSource(dataSource);
        // 指定主库 Mapper XML 路径（假设放在 resources/mapper/master 下）
        sessionFactory.setMapperLocations(new PathMatchingResourcePatternResolver()
                .getResources("classpath:mapper/master/*.xml"));
        // 实体类包（可选，MyBatis自动扫描）
        sessionFactory.setTypeAliasesPackage("com.example.entity");
        return sessionFactory.getObject();
    }

    // 从库 SqlSessionFactory
    @Bean("slaveSqlSessionFactory")
    public SqlSessionFactory slaveSqlSessionFactory(
            @Qualifier("slaveDataSource") DataSource dataSource) throws Exception {
        SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
        sessionFactory.setDataSource(dataSource);
        // 从库 Mapper XML 路径
        sessionFactory.setMapperLocations(new PathMatchingResourcePatternResolver()
                .getResources("classpath:mapper/slave/*.xml"));
        sessionFactory.setTypeAliasesPackage("com.example.entity");
        return sessionFactory.getObject();
    }

    // 主库事务管理器（必须和主库 SqlSessionFactory 绑定）
    @Bean("masterTransactionManager")
    public PlatformTransactionManager masterTransactionManager(
            @Qualifier("masterSqlSessionFactory") SqlSessionFactory sqlSessionFactory) {
        return new DataSourceTransactionManager(sqlSessionFactory.getDataSource());
    }

    // 从库事务管理器
    @Bean("slaveTransactionManager")
    public PlatformTransactionManager slaveTransactionManager(
            @Qualifier("slaveSqlSessionFactory") SqlSessionFactory sqlSessionFactory) {
        return new DataSourceTransactionManager(sqlSessionFactory.getDataSource());
    }
}

步骤5：指定Mapper使用的数据源

通过@MapperScan注解，告诉MyBatis不同的Mapper接口使用哪个SqlSessionFactory。例如：主库的Mapper放在com.example.mapper.master包下，从库的放在com.example.mapper.slave包下。

@SpringBootApplication
// 扫描主库 Mapper（使用 masterSqlSessionFactory）
@MapperScan(basePackages = "com.example.mapper.master", 
           sqlSessionFactoryRef = "masterSqlSessionFactory")
// 扫描从库 Mapper（使用 slaveSqlSessionFactory）
@MapperScan(basePackages = "com.example.mapper.slave", 
           sqlSessionFactoryRef = "slaveSqlSessionFactory")
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

静态多数据源的优缺点

优点：配置简单，适合数据源数量固定、无需动态切换的场景（如主从读写分离）。
缺点：数据源数量固定，无法运行时动态调整；如果数据源很多（比如10个租户），配置会变得冗余。

三、动态多数据源：运行时切换的终极方案

如果你的业务需要根据不同的租户、业务类型动态切换数据源（比如SaaS系统），静态多数据源就不够用了。这时候需要用动态数据源路由，核心是继承AbstractRoutingDataSource，重写determineCurrentLookupKey()方法。

步骤1：定义动态数据源路由类

通过ThreadLocal存储当前线程的数据源Key（比如master或slave），线程结束后清除Key，避免线程污染。

public class DynamicDataSource extends AbstractRoutingDataSource {

    // ThreadLocal 存储当前数据源 Key（线程隔离）
    private static final ThreadLocal<String> CONTEXT_HOLDER = new ThreadLocal<>();

    // 设置当前数据源 Key（在AOP中调用）
    public static void setDataSourceKey(String key) {
        CONTEXT_HOLDER.set(key);
    }

    // 清除当前数据源 Key（避免线程复用导致Key残留）
    public static void clearDataSourceKey() {
        CONTEXT_HOLDER.remove();
    }

    // 重写方法，返回当前数据源 Key
    @Override
    protected Object determineCurrentLookupKey() {
        return CONTEXT_HOLDER.get(); // 返回 null 会使用默认数据源
    }
}

步骤2：配置动态数据源Bean

将多个数据源（主库、从库、租户库）放入targetDataSources，并设置默认数据源（未指定Key时使用）。

@Configuration
public class DynamicDataSourceConfig {

    @Bean
    public DynamicDataSource dynamicDataSource(
            @Qualifier("masterDataSource") DataSource masterDataSource,
            @Qualifier("slaveDataSource") DataSource slaveDataSource) {

        DynamicDataSource dynamicDataSource = new DynamicDataSource();
        // 默认数据源（未指定Key时使用）
        Map<Object, Object> targetDataSources = new HashMap<>();
        targetDataSources.put("master", masterDataSource); // Key是"master"
        targetDataSources.put("slave", slaveDataSource);   // Key是"slave"
        dynamicDataSource.setTargetDataSources(targetDataSources);
        dynamicDataSource.setDefaultTargetDataSource(masterDataSource); // 默认主库
        return dynamicDataSource;
    }
}

步骤3：配置SqlSessionFactory和事务管理器

动态数据源的SqlSessionFactory和事务管理器与静态类似，但不需要为每个数据源单独配置，统一使用动态数据源。

@Configuration
public class DynamicSqlSessionFactoryConfig {

    @Bean("sqlSessionFactory")
    public SqlSessionFactory sqlSessionFactory(DynamicDataSource dynamicDataSource) throws Exception {
        SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
        sessionFactory.setDataSource(dynamicDataSource); // 使用动态数据源
        // 统一 Mapper XML 路径（所有数据源的Mapper放在一起）
        sessionFactory.setMapperLocations(new PathMatchingResourcePatternResolver()
                .getResources("classpath:mapper/*.xml"));
        sessionFactory.setTypeAliasesPackage("com.example.entity");
        return sessionFactory.getObject();
    }

    @Bean
    public PlatformTransactionManager transactionManager(DynamicDataSource dynamicDataSource) {
        return new DataSourceTransactionManager(dynamicDataSource);
    }
}

步骤4：通过AOP动态切换数据源

在需要切换数据源的方法上添加自定义注解（如@SlaveDS），通过AOP拦截并设置ThreadLocal中的Key。

4.1 定义自定义注解
// 注解可以加在方法或类上
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface SlaveDS {
}
4.2 编写AOP切面
@Aspect
@Component
public class DataSourceAspect {

    // 切入点：标注了@SlaveDS的方法
    @Pointcut("@annotation(com.example.annotation.SlaveDS)")
    public void slaveDSPointcut() {}

    // 方法执行前，切换为从库
    @Before("slaveDSPointcut()")
    public void before(JoinPoint joinPoint) {
        DynamicDataSource.setDataSourceKey("slave"); // 切换为从库
    }

    // 方法执行后，清除Key（重要！避免线程污染）
    @After("slaveDSPointcut()")
    public void after(JoinPoint joinPoint) {
        DynamicDataSource.clearDataSourceKey();
    }
}

步骤5：在Service中使用动态数据源

在需要访问从库的方法上添加@SlaveDS注解，MyBatis会自动使用从库的数据源。

@Service
public class UserService {

    @Autowired
    private UserMapper userMapper; // Mapper 接口（动态数据源）

    // 主库操作（默认，无需注解）
    public User getMasterUser(Long id) {
        return userMapper.selectById(id);
    }

    // 从库操作（通过@SlaveDS切换）
    @SlaveDS
    public User getSlaveUser(Long id) {
        return userMapper.selectById(id);
    }
}

动态多数据源的注意事项

  1. 线程安全：必须在@After中清除ThreadLocal的Key！否则线程池复用线程时，下一个请求可能错误地使用上一个请求的数据源。
  2. 事务限制：动态数据源切换后，本地事务只能作用于当前数据源。如果一个方法中同时操作主库和从库，事务无法保证原子性（需用分布式事务）。
  3. Mapper冲突：所有数据源的Mapper接口不能同名，否则@MapperScan会报错。建议按数据源分包（如master.mapper、slave.mapper）。

四、分布式事务：跨数据源的原子性

如果业务需要跨多个数据源操作（比如主库写+从库更新缓存），本地事务无法保证原子性，这时候需要分布式事务解决方案。

常见方案对比

方案原理优点缺点适用场景
XA协议两阶段提交（2PC）强一致性性能差，锁资源时间长对一致性要求极高的场景
Seata AT模式自动生成回滚日志无侵入，性能较好需要改造数据库（自增主键）微服务跨库场景
最终一致性消息队列补偿性能高，解耦实现复杂，有延迟对一致性要求不高的场景

五、实战踩坑指南（避坑！避坑！）

  1. 连接池配置错误：每个数据源必须独立配置连接池参数！如果主从库共用连接池，可能导致主库连接被从库耗尽。
  2. 事务失效：动态数据源切换后，如果在同一个方法中调用多个数据源的操作，必须使用分布式事务，否则本地事务无法生效。
  3. Mapper XML路径错误：静态多数据源中，不同数据源的Mapper XML路径必须严格区分，否则会报“重复映射”错误。
  4. ThreadLocal未清除：动态数据源中，如果忘记清除ThreadLocal的Key，线程池复用线程时会导致数据源切换错误（比如A用户的请求用了B用户的数据源）。

总结

MyBatis多数据源的核心是数据源的隔离与动态路由：

  • 静态多数据源适合固定场景（如主从读写分离），配置简单但扩展性差；
  • 动态多数据源通过AbstractRoutingDataSource和AOP实现运行时切换，适合多租户、SaaS等复杂场景；
  • 跨数据源操作需用分布式事务，根据业务需求选择XA、Seata或最终一致性方案。

最后，推荐大家试试MyBatis-Plus的dynamic-datasource模块，它内置了动态数据源支持，通过@DS注解就能轻松切换，能省去很多配置代码～

如果本文对你有帮助，欢迎点赞收藏，评论区一起交流！ 😊

MyBatis多数据源配置及动态切换——搭建多个数据源并动态切换
AI天才研究院
07-29 4024
随着互联网的蓬勃发展，网站的用户量和访问量越来越大，单个数据库已经无法承受如此巨大的访问量，而更好的解决方案是将数据分布到多个数据库服务器上，并通过读写分离的方式提高数据库负载能力和提升整体性能。为了实现这一目标，目前最流行的一种方式是使用读写分离的数据库架构模式。在这种架构模式下，应用层的数据请求会路由到主库或从库，由主库对数据进行写操作（INSERT、UPDATE等）后，同步给从库，保证主库中的数据的一致性。相比于单个数据库服务器，采用读写分离的架构模式最大的优点就是增加了灵活性。
1、SpringBoo中Mybatis多数据源动态切换
advent86的专栏
11-27 2195
Springboot,，数据源动态切换，mybatis动态创建数据源及动态切换数据源
Springboot整合Mybatis多数据源配置
热门推荐
小小史莱姆的博客
06-09 2万+
话不多说，直接进入正题。源码地址：https://github.com/AliceAsuna/KiritoV1.git 目录 一、数据库配置文件 二、配置类 主数据源配置类： 次数据源配置类： 三、项目结构（重点是mapper结构和配置类里的路径对应） 四、启动类——启动类需要取消加载数据源自动配置 五、测试： controller： Service： Mapper： 数据...
MyBatis 多数据源支持
FireFox1997
06-19 772
在复杂的企业级应用中，使用多个数据源是一个常见需求。本文详细介绍了如何使用 MyBatis 配置和使用多个数据源，包括配置数据源、创建数据源配置类、配置 Mapper、创建 Mapper 接口以及在 Service 层使用多个数据源。通过这些步骤，可以轻松实现 MyBatis 多数据源的支持，提高系统的扩展性和灵活性。MyBatis 官方文档Spring Boot 官方文档希望本文对你有所帮助，能够更好地利用 MyBatis 的多数据源支持来实现高效的数据库管理。
MyBatis-Plus多数据源配置：轻松实现数据库切换
最新发布
m0_65382359的博客
06-13 2439
/ 设置权重// 70%的概率// 30%的概率@Override.sum();return ds;
MyBatis 多数据源
小心仔的博客
10-19 1688
一、AOP多数据源 二、配合注解实现
MyBatisPlus--多数据源
qq_45917176的博客
04-21 1万+
官网地址：多数据源 | MyBatis-Plus (baomidou.com) 支持 数据源分组 ，适用于多种场景、纯粹多库、读写分离、一主多从、混合模式。 目前来模拟一个纯粹多库的一个场景，其他场景类似；场景说明： 创建两个库，分别为：mybatis_plus与mybatis_plus_1，使每个库一张表，通过一个测试用例分别获取用户数据与商品数据，如果获取到说明多库模拟成功。 1、创建数据库及表 创建数据库mybatis_plus和表user CREATE DATABASE `mybatis_plu.
mybatis多数据源
m0_37696940的博客
07-13 832
mybatis多数据源配置
MyBatis多数据源配置详解：两种方式与示例
在MyBatis框架中，处理多数据源的需求是一项常见的任务，特别是在项目中涉及多个独立数据库或主从复制场景时。本文将深入探讨MyBatis支持的两种主要配置多数据源的方式。 首先，我们区分两种多数据源情况： 1. 独立...
MyBatis 多数据源切换：AbstractRoutingDataSource 与拦截器对比及实现实战
2301_76740633的博客
06-03 2732
MyBatis实现多数据源切换主要采用两种方案：基于Spring AbstractRoutingDataSource的动态路由和基于MyBatis拦截器的切换机制。前者通过继承AbstractRoutingDataSource重写determineCurrentLookupKey方法，利用ThreadLocal存储数据源标识，适合方法级别切换和Spring事务集成；后者通过拦截Executor的query/update方法，支持SQL语句级别的细粒度控制。
springboot配置多数据库 - dynamic
编写博客，学习交流
11-29 2382
码云地址: dynamic-datasource-spring-boot-starter: 基于 SpringBoot 多数据源 动态数据源 主从分离 快速启动器 支持分布式事务https://gitee.com/baomidou/dynamic-datasource-spring-boot-starter dynamic-datasource-spring-boot-starter 是一个基于springboot的快速集成多数据源的启动器。 文档 | Documentation 详细文档基础.
Mybatis配置多数据源
weixin_44385360的博客
11-30 1万+
Spring Boot项目使用Mybatis，既要从上游系统同步数据，又要操作本系统的数据库，所以需要引入双数据源，配置Mybatis。
mybatis配置多数据源
weixin_39672065的博客
04-27 2191
先将spring boot自带的DataSourceAutoConfiguration禁掉，因为它会读取application.properties文件的spring.datasource.*属性并自动配置单数据源。在@SpringBootApplication注解中添加exclude属性即可： @SpringBootApplication(exclude = { DataSourceAutoConfiguration.class }) public class Application {
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

码不停蹄的玄黓

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值