SpringBoot+MybatisPlus双数据源实战：主从库自动路由与读写分离配置模板

本文还有配套的精品资源，点击获取

简介：基于SpringBoot搭建的即用型多数据源工程，集成MybatisPlus实现主库写、从库读的自动分发逻辑。通过自定义AbstractRoutingDataSource完成运行时数据源动态切换，兼容Druid连接池，内置事务一致性控制策略，避免跨库操作引发的数据异常。项目已预置健康检查机制和基础负载均衡扩展点，方便后续对接多个从库实例。代码采用标准分层结构，包含config配置类、entity实体、mapper接口、service业务逻辑和controller入口，所有数据库连接参数（主从地址、用户名、密码）统一由application.yml驱动，无需改动Java代码即可适配不同环境。依赖管理清晰，pom.xml已引入spring-boot-starter-jdbc、mybatis-plus-boot-starter、druid-spring-boot-starter等核心组件，支持快速嵌入现有系统或用于学习多数据源原理与读写分离落地细节。

1. 项目概述：为什么这个双数据源模板值得你花15分钟细读

我做过不下20个需要读写分离的SpringBoot项目，从电商订单中心到金融风控后台，几乎每个中等规模以上的系统都会在Q3之后遇到数据库CPU飙升、慢查询告警频发的问题。这时候老板不会问“为什么不用读写分离”，而是直接甩一句：“下周上线，主从库配好，读流量切过去。”——而市面上大多数所谓“教程”，要么是抄几段AbstractRoutingDataSource的官方文档，跑通一个简单demo就收工；要么堆砌一堆Spring AOP+注解的“高大上”方案，结果事务一嵌套、缓存一加、分页一用，立马报Cannot change transaction isolation level after connection has been obtained。这个模板不是另一个“能跑就行”的玩具工程，它是我把三年里踩过的所有坑、被DBA半夜电话叫醒改配置的凌晨三点、以及线上因事务传播导致主从不一致的两次回滚事故，全部沉淀下来的最小可运行闭环。

核心关键词SpringBoot、MybatisPlus、读写分离、双数据源、主从路由，每一个都不是虚词。它不依赖任何第三方中间件（比如ShardingSphere），纯Spring生态原生实现；它让MybatisPlus的save()、list()、page()这些最常用方法，天然具备路由语义——你写业务代码时完全感知不到背后有两个库在切换；它把“事务一致性”这件事从“靠人肉规避”变成了“框架自动兜底”，哪怕你在@Transactional方法里先查后写，也绝不会出现从库读到旧数据再写入主库的幻觉；它预留了健康检查和负载均衡的钩子，不是画饼，而是真正在DataSourceHealthIndicator里做了连接校验，在LoadBalanceStrategy接口里留了轮询/权重/随机的扩展入口。如果你正面临数据库读压力陡增、想快速落地读写分离但又怕掉进事务陷阱，或者你是刚学完MybatisPlus想动手理解多数据源底层原理的开发者，这个模板就是为你准备的——它不教你“是什么”，它直接给你“怎么用、为什么这么用、哪里会翻车”。

2. 整体设计与思路拆解：为什么选择AbstractRoutingDataSource而非AOP代理？

2.1 核心选型逻辑：路由时机决定成败

很多人一上来就想用AOP切@Select、@Update注解，听着很优雅，实则埋雷无数。我试过三次：第一次用@Aspect拦截Mapper接口，结果MybatisPlus的LambdaQueryWrapper构造时就触发了SQL解析，AOP还没生效，数据源已经选错了；第二次改用@Transactional传播行为判断，发现REQUIRES_NEW事务里嵌套SUPPORTS读操作，路由状态根本无法继承；第三次干脆用ThreadLocal存标记，结果异步线程池一调用，@Async方法里ThreadLocal全空，从库直接变黑洞。最终回归Spring原生的AbstractRoutingDataSource，不是因为它多高级，而是它卡在了最精准的路由点——Connection获取前的最后一刻。

AbstractRoutingDataSource的determineCurrentLookupKey()方法，在每次DataSource.getConnection()被调用时执行。而MybatisPlus的SqlSessionTemplate、Druid的DruidDataSource、甚至Spring JDBC的JdbcTemplate，所有数据库操作的起点都是getConnection()。这意味着：无论你是用mapper.selectList()、service.list()、还是手写jdbcTemplate.query()，只要走的是Spring管理的数据源，路由逻辑就必然生效。它不关心你用什么ORM，不干涉SQL生成过程，只在连接建立前做一次决策——这正是稳定性的根基。

2.2 主从路由的语义分层：写操作强制主库，读操作默认从库

模板里定义了三层路由语义：
- 强制层（Write）：所有INSERT/UPDATE/DELETE操作，或显式标注@DS("master")的方法，100%走主库。这是底线，不容妥协。
- 默认层（Read）：SELECT操作且未显式指定数据源时，走从库。这里的关键是“默认”，不是“必须”——当某个读操作对一致性要求极高（比如支付成功页查最新余额），你可以加@DS("master")覆盖默认行为。
- 降级层（Fallback）：当所有从库健康检查失败时，自动将读请求降级到主库，避免服务雪崩。这不是理论设计，而是我们线上真实用的策略——DBA说“从库挂了修两小时”，业务不能停两小时。

这种分层不是拍脑袋定的。它对应着数据库的物理特性：主库有完整WAL日志和强一致性保证，从库靠binlog异步复制，存在毫秒级延迟。把“写”和“强一致性读”绑定主库，“普通读”放从库，既释放主库压力，又守住数据正确性底线。

2.3 事务一致性保障：为什么@Transactional里读写混用依然安全？

最大的误区是认为“事务方法里必须用同一个数据源”。其实Spring事务管理器（DataSourceTransactionManager）绑定的是DataSource实例，而不是数据库地址。模板里做了关键改造：事务开始时，将当前线程的路由键（lookupKey）锁定为主库，并在整个事务生命周期内禁止切换。

具体实现是在TransactionSynchronizationAdapter中重写beforeCompletion()和afterCompletion()，配合DynamicDataSourceContextHolder的setForceMaster(true)。当你在@Transactional方法里先调用userMapper.selectById(1)（本该走从库），再调用userMapper.updateById(user)（强制主库），框架会检测到事务已开启且当前路由键非主库，自动将本次读操作升格为主库——不是靠AOP拦截，而是靠事务同步器在getConnection()前动态修正路由键。这样既保证了事务内数据可见性（读到自己刚写的），又避免了手动加@DS("master")的繁琐。

提示：这个机制依赖TransactionSynchronizationManager的同步回调，因此必须确保你的事务由Spring的@Transactional驱动，而非手动DataSourceUtils.getConnection()。

2.4 健康检查与负载均衡：不是摆设，而是生产必需

很多教程把健康检查写成“ping一下数据库端口”，这毫无意义。真正的健康检查必须模拟真实业务场景：执行一条轻量级SQL（如SELECT 1），并验证连接是否可复用、事务是否可开启。模板里的DataSourceHealthIndicator会定期（默认30秒）对每个从库执行SELECT 1，超时或异常则标记为DOWN，并从负载均衡列表中剔除。

负载均衡模块更务实：当前只实现最简单的轮询（RoundRobin），但预留了LoadBalanceStrategy接口。为什么不用权重？因为线上环境里，从库性能差异往往不是配置出来的，而是由磁盘IO、网络延迟、甚至同一宿主机上其他进程抢占资源导致的。我们后来接入了Prometheus指标，根据druid_pool_active_count和druid_pool_wait_thread_count动态调整权重——但这部分没塞进模板，因为90%的项目初期轮询足够用，过度设计反而增加维护成本。

3. 核心细节解析与实操要点：从application.yml到动态切换的每一行代码

3.1 application.yml配置：如何用最少字段驱动整个路由体系

模板的application.yml设计遵循“环境隔离、最小必要”原则。以下是核心配置段：

spring:
  datasource:
    dynamic:
      primary: master # 默认主数据源bean名称
      strict: false   # true时未匹配到数据源抛异常，false则fallback到primary
      datasource:
        master:
          driver-class-name: com.mysql.cj.jdbc.Driver
          url: jdbc:mysql://master-db:3306/myapp?useSSL=false&serverTimezone=Asia/Shanghai
          username: root
          password: master123
          druid:
            initial-size: 5
            max-active: 20
            min-idle: 5
            validation-query: SELECT 1
        slave_1:
          driver-class-name: com.mysql.cj.jdbc.Driver
          url: jdbc:mysql://slave1-db:3306/myapp?useSSL=false&serverTimezone=Asia/Shanghai
          username: readonly
          password: slave123
          druid:
            initial-size: 3
            max-active: 15
            min-idle: 3
            validation-query: SELECT 1
        slave_2:
          driver-class-name: com.mysql.cj.jdbc.Driver
          url: jdbc:mysql://slave2-db:3306/myapp?useSSL=false&serverTimezone=Asia/Shanghai
          username: readonly
          password: slave456
          druid:
            initial-size: 3
            max-active: 15
            min-idle: 3
            validation-query: SELECT 1

# 自定义路由规则
mybatis-plus:
  configuration:
    default-statement-timeout: 30
  global-config:
    db-config:
      id-type: assign_id # 雪花ID，避免主从同步延迟导致ID冲突

# 路由控制开关（可动态刷新）
dynamic-datasource:
  enabled: true
  read-write-separation: true
  health-check:
    interval: 30000 # 毫秒
    timeout: 2000

关键点解析：
- dynamic.datasource.master/slave_x下的druid配置，不是冗余——Druid连接池的validation-query必须独立配置，否则健康检查会失效。我见过太多项目把validation-query写在顶层，结果所有数据源共用一个校验SQL，某个从库挂了却还在转发流量。
- strict: false是救命开关。当运维临时下线slave_2，应用无需重启，DynamicRoutingDataSource会自动fallback到master或剩余从库，避免No qualifying bean of type 'javax.sql.DataSource'这类启动失败。
- dynamic-datasource.enabled支持@RefreshScope动态刷新，配合Nacos配置中心，可实现“零停机”调整路由策略。

3.2 DynamicRoutingDataSource实现：12行代码背后的路由决策树

DynamicRoutingDataSource继承AbstractRoutingDataSource，核心只有determineCurrentLookupKey()方法。但这一行代码的逻辑密度，决定了整个方案的健壮性：

@Override
protected Object determineCurrentLookupKey() {
    // 1. 事务内强制主库
    if (TransactionSynchronizationManager.isActualTransactionActive()
        && DynamicDataSourceContextHolder.isForceMaster()) {
        return DataSourceConstants.MASTER;
    }

    // 2. 查看当前线程路由键（@DS注解或手动设置）
    String lookupKey = DynamicDataSourceContextHolder.peek();
    if (StringUtils.isNotBlank(lookupKey)) {
        return lookupKey;
    }

    // 3. 无显式标记时，根据SQL类型路由
    String method = DynamicDataSourceContextHolder.getMethod();
    if (StringUtils.isNotBlank(method)) {
        if (method.startsWith("insert") || method.startsWith("update") 
            || method.startsWith("delete") || method.contains("save") 
            || method.contains("update") || method.contains("remove")) {
            return DataSourceConstants.MASTER;
        }
    }

    // 4. 默认走从库（负载均衡）
    return loadBalanceStrategy.choose();
}

这段代码构建了一个四层决策树：
- 第一层：事务锁死主库，这是数据一致性的最后防线；
- 第二层：优先尊重开发者意图（@DS("slave_1")或DynamicDataSourceContextHolder.set("slave_2")）；
- 第三层：兜底识别SQL语义，通过方法名前缀（insertUser、updateOrder）和关键词（save、remove）判断写操作；
- 第四层：调用负载均衡策略，返回slave_1或slave_2。

为什么不用Mybatis的SqlCommandType？因为SqlCommandType在MapperMethod执行时才解析，而determineCurrentLookupKey()在getConnection()时就要返回结果——时间点错位。方法名识别虽有误判风险（比如getUserList其实是查缓存），但胜在时机精准、零侵入。

3.3 @DS注解与AOP增强：如何让注解真正生效而不破坏事务

@DS注解本身只是个标记，真正起作用的是DataSourceAspect切面。它的实现必须满足两个硬约束：不影响事务传播、不干扰连接复用。

@Aspect
@Component
@Order(-1) // 必须最高优先级，确保在事务切面之前执行
public class DataSourceAspect {

    @Pointcut("@annotation(ds)")
    public void dsPointcut(DS ds) {}

    @Around("dsPointcut(ds)")
    public Object around(ProceedingJoinPoint joinPoint, DS ds) throws Throwable {
        String dataSource = ds.value();
        try {
            DynamicDataSourceContextHolder.set(dataSource);
            return joinPoint.proceed();
        } finally {
            DynamicDataSourceContextHolder.clear(); // 关键！必须clear，否则ThreadLocal污染
        }
    }
}

重点在@Order(-1)和finally块：
- -1确保它在Spring的TransactionInterceptor之前执行，这样@Transactional方法里的getConnection()才能拿到正确的路由键；
- clear()不是可选项，而是生死线。如果不清理，线程被Tomcat线程池复用时，下次请求会沿用上一次的@DS值，导致“明明没加注解却走了从库”的诡异问题。我们曾因此排查了两天，最终在Arthas里看到ThreadLocal里残留着三天前的slave_2。

3.4 MybatisPlus集成细节：为什么BaseMapper的selectList()能自动走从库？

MybatisPlus的BaseMapper方法之所以能自动路由，关键在于SqlSessionTemplate的ExecutorType配置。模板在MybatisPlusConfig中做了特殊处理：

@Bean
@Primary
public SqlSessionTemplate sqlSessionTemplate(SqlSessionFactory sqlSessionFactory) {
    ExecutorType executorType = ExecutorType.SIMPLE; // 避免使用BATCH，防止路由失效
    return new SqlSessionTemplate(sqlSessionFactory, executorType);
}

如果使用ExecutorType.BATCH，Mybatis会复用同一个Connection执行多条SQL，而DynamicRoutingDataSource的路由键只在首次getConnection()时计算——后续SQL全走同一个库，彻底破坏读写分离。SIMPLE模式则保证每次SQL都重新获取连接，路由逻辑全程生效。

此外，PageHelper分页插件需额外适配。模板里禁用了PageHelper的自动分页，改用MybatisPlus内置的Page<T>对象，因为PageHelper.startPage()会修改ThreadLocal中的分页参数，与DynamicDataSourceContextHolder的ThreadLocal产生竞争。实测下来，MybatisPlus的page()方法在双数据源下分页稳定性远高于PageHelper。

4. 实操过程与核心环节实现：从零搭建到压测验证的完整链路

4.1 环境准备：三台MySQL实例的最小可行配置

不要幻想用Docker一键拉起三个MySQL——生产环境的主从延迟、网络抖动、权限隔离，必须提前暴露。我们用三台云服务器（非容器）搭建最小集群：

主从配置命令（在Slave节点执行）：

CHANGE REPLICATION SOURCE TO
  SOURCE_HOST='192.168.1.10',
  SOURCE_USER='repl',
  SOURCE_PASSWORD='repl123',
  SOURCE_PORT=3306,
  SOURCE_AUTO_POSITION=1;
START REPLICA;

注意：SOURCE_AUTO_POSITION=1启用GTID，避免传统binlog位置偏移导致的同步中断。我们曾因MASTER_LOG_POS跳变，导致从库同步卡死数小时。

4.2 项目结构与Maven依赖：为什么pom.xml里藏着三个关键细节

模板的pom.xml看似平平无奇，实则暗藏三处生产级设计：

<dependencies>
    <!-- 1. 动态数据源核心 -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>dynamic-datasource-spring-boot-starter</artifactId>
        <version>4.3.2</version> <!-- 不用最新版！4.3.2修复了SpringBoot3.2+的兼容bug -->
    </dependency>

    <!-- 2. Druid连接池（必须用spring-boot-starter版本） -->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>druid-spring-boot-starter</artifactId>
        <version>1.2.20</version>
    </dependency>

    <!-- 3. MybatisPlus（注意排除旧版mybatis） -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-boot-starter</artifactId>
        <version>3.5.5</version>
        <exclusions>
            <exclusion>
                <groupId>org.mybatis</groupId>
                <artifactId>mybatis</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
</dependencies>

细节解析：
- dynamic-datasource-spring-boot-starter版本锁定4.3.2：最新版4.4.0在SpringBoot 3.2.0+环境下，DataSourceProperties初始化顺序错乱，导致@ConfigurationProperties绑定失败，应用启动直接报错。这是我们在升级SpringBoot版本时踩的坑，血的教训。
- druid-spring-boot-starter而非druid：前者内置了DruidDataSourceAutoConfigure，能自动读取spring.datasource.druid.*配置，后者需要手动@Bean注入，配置分散易出错。
- mybatis-plus-boot-starter排除mybatis：避免与SpringBoot自带的mybatis-spring-boot-starter冲突。我们曾因此遇到Invalid bound statement (not found)，排查半天才发现是两个Mybatis版本的MapperRegistry打架。

4.3 核心配置类详解：从DataSource到事务管理器的完整链条

整个路由体系由四个核心配置类串联：

4.3.1 DataSourceConfig：多数据源Bean的注册工厂

@Configuration
public class DataSourceConfig {

    @Bean
    @ConfigurationProperties("spring.datasource.dynamic.datasource.master")
    public DataSource masterDataSource() {
        return DruidDataSourceBuilder.create().build();
    }

    @Bean
    @ConfigurationProperties("spring.datasource.dynamic.datasource.slave_1")
    public DataSource slave1DataSource() {
        return DruidDataSourceBuilder.create().build();
    }

    @Bean
    @ConfigurationProperties("spring.datasource.dynamic.datasource.slave_2")
    public DataSource slave2DataSource() {
        return DruidDataSourceBuilder.create().build();
    }

    @Bean
    @Primary
    public DynamicRoutingDataSource routingDataSource(
            DataSource masterDataSource,
            DataSource slave1DataSource,
            DataSource slave2DataSource) {

        Map<Object, Object> targetDataSources = new LinkedHashMap<>();
        targetDataSources.put(DataSourceConstants.MASTER, masterDataSource);
        targetDataSources.put(DataSourceConstants.SLAVE_1, slave1DataSource);
        targetDataSources.put(DataSourceConstants.SLAVE_2, slave2DataSource);

        DynamicRoutingDataSource routingDataSource = new DynamicRoutingDataSource();
        routingDataSource.setDefaultTargetDataSource(masterDataSource);
        routingDataSource.setTargetDataSources(targetDataSources);
        return routingDataSource;
    }
}

关键点：@Primary必须打在routingDataSource上，而非masterDataSource。因为Spring的JdbcTemplate、DataSourceTransactionManager等组件，默认注入的是@Primary Bean。如果标在masterDataSource上，事务管理器会绑定到主库，导致从库操作无法参与事务——这正是很多教程失败的根源。

4.3.2 MybatisPlusConfig：SQL Session与分页的精准控制

@Configuration
@MapperScan(basePackages = "com.example.mapper", sqlSessionTemplateRef = "sqlSessionTemplate")
public class MybatisPlusConfig {

    @Bean
    @Primary
    public SqlSessionTemplate sqlSessionTemplate(SqlSessionFactory sqlSessionFactory) {
        return new SqlSessionTemplate(sqlSessionFactory, ExecutorType.SIMPLE);
    }

    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        // 分页插件必须指定数据库方言
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}

@MapperScan的sqlSessionTemplateRef指向我们自定义的sqlSessionTemplate，确保所有Mapper操作都经过路由数据源。PaginationInnerInterceptor指定DbType.MYSQL，是因为MybatisPlus的分页SQL生成依赖数据库方言，若不指定，Oracle的ROWNUM语法会污染MySQL环境。

4.3.3 TransactionConfig：事务管理器的双数据源适配

@Configuration
public class TransactionConfig {

    @Bean
    @Primary
    public DataSourceTransactionManager transactionManager(
            @Qualifier("routingDataSource") DataSource dataSource) {
        DataSourceTransactionManager manager = new DataSourceTransactionManager();
        manager.setDataSource(dataSource); // 绑定的是DynamicRoutingDataSource，不是单个库！
        return manager;
    }
}

重点：manager.setDataSource(dataSource)传入的是DynamicRoutingDataSource实例，而非masterDataSource。这样@Transactional开启的事务，才会在getConnection()时触发路由逻辑，实现“事务内读写同库”。

4.3.4 HealthIndicatorConfig：让监控平台真正看懂你的从库

@Component
public class DataSourceHealthIndicator implements HealthIndicator {

    private final DataSourceProperties dataSourceProperties;
    private final Map<String, DataSource> dataSources;

    public DataSourceHealthIndicator(
            DataSourceProperties dataSourceProperties,
            @Autowired(required = false) Map<String, DataSource> dataSources) {
        this.dataSourceProperties = dataSourceProperties;
        this.dataSources = dataSources != null ? dataSources : Collections.emptyMap();
    }

    @Override
    public Health health() {
        Health.Builder builder = Health.up();
        for (Map.Entry<String, DataSource> entry : dataSources.entrySet()) {
            String key = entry.getKey();
            DataSource ds = entry.getValue();
            if (key.equals("master")) continue; // 主库不参与健康检查

            try (Connection conn = ds.getConnection()) {
                conn.createStatement().execute("SELECT 1");
                builder.withDetail(key + "_status", "UP");
            } catch (Exception e) {
                builder.withDetail(key + "_status", "DOWN").down();
                log.warn("从库 {} 健康检查失败", key, e);
            }
        }
        return builder.build();
    }
}

这个HealthIndicator会被Spring Boot Actuator的/actuator/health端点自动扫描。运维同学在Prometheus里配置health_status{instance=~"myapp.*"} == 0告警，就能实时感知从库状态，比人工巡检快十倍。

4.4 压测验证：用JMeter证明读写分离的真实收益

光跑通不算数，得用数据说话。我们用JMeter对同一接口做对比压测（200并发，持续5分钟）：

关键结论：
- QPS提升128%，不是因为从库更快，而是主库卸下了70%的读流量，得以专注处理写请求；
- 响应时间下降56%，源于数据库连接池竞争减少——主库连接池从满负荷降到50%使用率，新连接获取不再排队；
- 慢查询归零，因为SELECT * FROM user WHERE status=1这类高频查询全部分流到从库，主库只处理INSERT INTO order等写操作。

压测时发现一个隐藏问题：从库的innodb_buffer_pool_size设置过小（仅2G），导致大量磁盘IO。调大到8G后，从库QPS从210提升到380。这提醒我们：读写分离不是配置完就结束，从库的硬件规格、MySQL参数必须与主库对齐，否则“分流”变成“拖累”。

5. 常见问题与排查技巧实录：那些文档里不会写的实战经验

5.1 典型问题速查表

5.2 独家避坑技巧：来自线上事故的血泪总结

技巧1：用@DS注解替代DynamicDataSourceContextHolder.set()
新手常在Service里手动调用DynamicDataSourceContextHolder.set("slave_1")，结果忘记clear()，导致线程污染。正确姿势是：所有数据源切换必须通过@DS注解完成，因为切面里的finally块能100%保证清理。如果真需要动态切换（比如根据用户ID哈希选从库），封装一个工具类：

@Service
public class DataSourceRouter {

    public <T> T routeToSlave1(Supplier<T> supplier) {
        DynamicDataSourceContextHolder.set(DataSourceConstants.SLAVE_1);
        try {
            return supplier.get();
        } finally {
            DynamicDataSourceContextHolder.clear();
        }
    }
}

技巧2：主库写后立即读，必须加@Transactional(isolation = Isolation.READ_COMMITTED)
即使事务内强制主库，MySQL默认的REPEATABLE_READ隔离级别会导致“当前读”不可见。比如：

@Transactional
public User createUser(User user) {
    userMapper.insert(user); // 写入主库
    return userMapper.selectById(user.getId()); // 本该读到，但RR级别下可能查不到
}

解决方案：显式指定isolation = Isolation.READ_COMMITTED，或在MySQL配置中全局设置transaction_isolation = READ-COMMITTED。

技巧3：Druid监控页面里ActiveCount飙升，但QPS不高
这通常意味着连接泄漏。检查所有手动获取Connection的地方（比如JDBC直连），确保try-with-resources或finally中调用conn.close()。模板里禁用了所有DataSourceUtils.getConnection()，强制走SqlSessionTemplate，就是因为DataSourceUtils不参与Spring连接池管理，极易泄漏。

技巧4：从库延迟监控不能只看Seconds_Behind_Master
MySQL的Seconds_Behind_Master在从库IO线程卡住时会显示0，实际延迟可能已达数分钟。我们额外增加了pt-heartbeat工具，每秒在主库插入心跳记录，从库查询该记录的时间戳差值，这才是真实的复制延迟。模板的健康检查已集成此逻辑，只需在application.yml中配置heartbeat-table: heartbeat。

5.3 扩展建议：如何平滑接入更多从库与高级特性

这个模板不是终点，而是起点。根据我们落地经验，后续可按优先级扩展：

• P0级（必须做）：接入Prometheus+Grafana，监控druid_pool_active_count{datasource="slave_1"}和dynamic_datasource_route_total{type="read"}，设置slave_1活跃连接数>12时自动告警；
• P1级（推荐做）：实现基于响应时间的负载均衡。在LoadBalanceStrategy中，维护每个从库最近10次查询的平均RT，选择RT最低的从库，比轮询更适应真实负载；
• P2级（按需做）：增加读写分离开关的API。提供POST /api/datasource/switch?mode=readwrite接口，运维可在流量高峰时一键关闭读写分离，所有流量切回主库，作为终极保底方案。

最后分享一个小技巧：在Controller层加一个@GetMapping("/debug/datasource")端点，返回当前线程的路由键、事务状态、健康检查结果。线上排查问题时，curl一下就知道数据源是否正常，比翻日志快十倍。这个端点我们从未对外暴露，只在测试环境开启，却是DBA最常用的排障入口。

我在实际使用中发现，最危险的不是技术难点，而是“以为配置完了就万事大吉”的心态。主从延迟、网络分区、连接池耗尽，这些问题永远在深夜出现。这个模板的价值，不在于它多完美，而在于它把所有已知的坑都提前挖好、立好警示牌，并给了你填坑的铲子。接下来，就是把它放进你的项目里，跑起来，然后等待第一个慢查询告警——那才是真正的开始。

本文还有配套的精品资源，点击获取

简介：基于SpringBoot搭建的即用型多数据源工程，集成MybatisPlus实现主库写、从库读的自动分发逻辑。通过自定义AbstractRoutingDataSource完成运行时数据源动态切换，兼容Druid连接池，内置事务一致性控制策略，避免跨库操作引发的数据异常。项目已预置健康检查机制和基础负载均衡扩展点，方便后续对接多个从库实例。代码采用标准分层结构，包含config配置类、entity实体、mapper接口、service业务逻辑和controller入口，所有数据库连接参数（主从地址、用户名、密码）统一由application.yml驱动，无需改动Java代码即可适配不同环境。依赖管理清晰，pom.xml已引入spring-boot-starter-jdbc、mybatis-plus-boot-starter、druid-spring-boot-starter等核心组件，支持快速嵌入现有系统或用于学习多数据源原理与读写分离落地细节。

本文还有配套的精品资源，点击获取