简介这份资源面向需要掌握多数据源与分库分表技术的 Spring Boot 开发者聚焦同一数据库内水平分表与跨库分库两类场景解决单表数据膨胀、多数据源切换与读写路由等实际问题适合具备一定 Spring Boot 与 MyBatis 基础、希望进阶分布式数据访问的中级开发者。项目采用 Spring Boot 搭建多数据源基于 mybatis-plus 的 dynamic-datasource 实现分库分表由 sharding-jdbc 承担连接池选用 alibaba 的 druid-spring-boot-starter并继承 MyBatis-Plus 简化数据库操作、引入 Lombok 精简实体代码配合 JUnit 完成测试验证。压缩包共 162 个文件以 115 个 xml 映射与配置、14 个 java 源码、14 个 class 编译文件为主另有 6 个 yml、3 个 properties 等配置文件整体约 164KB结构紧凑便于按模块查阅。目前已有 624 人学习可帮助读者理解多数据源动态切换、分库分表规则配置与测试用例组织方式快速搭建可运行的示例工程并对照源码排查配置问题。1. 多数据源与分库分表为什么“加个注解就切换”往往是最危险的设计很多人第一次接触多数据源是从一个DS(slave)注解开始的——方法上标一下连接就切过去了看起来优雅得像魔法。但真正在生产里跑过一段时间的人会发现这套“注解即切换”的模型在事务、异步线程、嵌套调用、连接池预热这几个场景下会接连翻车。原因不复杂数据源切换的本质是在 ThreadLocal 里放一个路由键再由AbstractRoutingDataSource在getConnection()时读出来决定去哪个库而 ThreadLocal 的可见性边界恰好和事务传播、线程池复用、AOP 代理顺序全都对不上。Spring Boot 生态里做多数据源和分库分表的方案很多但底层机制就那么几层路由键的存放、连接的选择、事务的绑定、SQL 的改写与归并。把这几层拆开看你才会明白为什么有些配置“能跑但不可靠”也才知道分库分表真正难的不是拆而是拆完之后那条查询怎么拼回来。2. 路由机制AbstractRoutingDataSource到底在什么时候决定用哪个库2.1 路由键存在哪ThreadLocal 的可见性边界Spring 的AbstractRoutingDataSource继承自AbstractDataSource核心只有一个抽象方法determineCurrentLookupKey()。它在getConnection()被调用时执行返回值作为 key 去targetDataSources这个 Map 里找真正的DataSource。常见的实现思路是把路由键放进ThreadLocal因为一次请求内绝大多数数据库操作都发生在同一个线程上。public class DynamicDataSource extends AbstractRoutingDataSource { Override protected Object determineCurrentLookupKey() { // 从 ThreadLocal 取出当前线程绑定的数据源标识 return DataSourceContextHolder.get(); } } public final class DataSourceContextHolder { // 用 ThreadLocal 保存路由键线程隔离 private static final ThreadLocalString CONTEXT new ThreadLocal(); public static void set(String key) { CONTEXT.set(key); } public static String get() { return CONTEXT.get(); } // 用完必须清理否则线程池复用会串库 public static void clear() { CONTEXT.remove(); } }这段代码的关键不在set而在clear。ThreadLocal的生命周期跟着线程走而 Web 容器和业务线程池都会复用线程。如果一次请求结束时没有remove()下一个请求复用同一线程时读到的就是上一个请求残留的路由键——这就是最典型的“串库”事故。我一般会把这个清理动作放在拦截器的afterCompletion里并且用try-finally包住保证异常路径也能清掉。determineCurrentLookupKey()的调用时机也值得注意它不是在方法进入时调一次而是每次获取连接都会调。这意味着同一个事务里如果中途改了 ThreadLocal 的值后续拿到的连接可能来自另一个库——而事务已经绑定在第一个连接上了结果就是部分操作游离在事务之外。这是理解后面所有坑的前提。2.2 AOP 切面与事务的先后顺序谁包住谁注解式切换通常靠一个Around切面在方法执行前set、执行后clear。问题在于 Spring 的事务也是 AOP两个切面的顺序决定了行为。如果数据源切面在事务切面外层那么事务开启时路由键已经就位DataSourceTransactionManager拿到的连接来自正确的库如果顺序反了事务先开启、连接先绑定切面再改路由键就完全无效——方法里所有 SQL 还是走原来的库。常见的实现思路是给数据源切面显式指定Order(Ordered.HIGHEST_PRECEDENCE)让它比Transactional更早进入。但更稳妥的做法是不要在同一个方法上既开事务又切数据源而是把数据源切换放在事务方法的外层调用者上。因为一旦事务已经绑定连接中途换库在 JDBC 层面就是不成立的——一个Connection对应一个物理库跨库事务需要分布式事务框架不是切个注解能解决的。2.3 嵌套调用时路由键的覆盖问题假设方法 A 标了DS(master)内部调用方法 B 标了DS(slave)。如果切面是简单的set后clearB 执行完clear会把整个 ThreadLocal 清空回到 A 继续执行时路由键已经没了determineCurrentLookupKey()返回 null落到默认数据源——可能既不是 master 也不是 slave。正确的做法是保存旧值、执行、恢复旧值类似栈的语义Around(annotation(ds)) public Object around(ProceedingJoinPoint pjp, DS ds) throws Throwable { String previous DataSourceContextHolder.get(); // 记住外层路由键 try { DataSourceContextHolder.set(ds.value()); return pjp.proceed(); } finally { // 恢复而不是清空保证嵌套调用能回到外层数据源 if (previous null) { DataSourceContextHolder.clear(); } else { DataSourceContextHolder.set(previous); } } }这个细节在单层调用里完全看不出来一旦出现 Service 互相调用就暴露。血泪经验是凡是操作 ThreadLocal 的切面都要按“保存—修改—恢复”写而不是“设置—清空”。3. 分库分表的 SQL 改写一条SELECT是怎么被拆成 N 条再拼回来的3.1 解析、路由、改写、归并四步流水线分库分表中间件无论客户端模式还是代理模式处理一条 SQL 的流程基本固定SQL 解析 → 分片路由 → SQL 改写 → 结果归并。以SELECT * FROM t_order WHERE user_id 100 AND order_id IN (1,2,3)为例如果分片键是user_id路由阶段算出100落在ds_1.t_order_0改写阶段把表名替换成实际物理表归并阶段把结果集合并返回。难点在于分片键不在条件里。SELECT * FROM t_order WHERE order_id 5这种查询路由阶段无法定位到具体分片只能全路由——向所有分片各发一条 SQL再把结果归并。这就是为什么分库分表后“非分片键查询”会突然变慢不是数据库慢了是查询被放大成了 N 倍。常见的实现思路是引入基因法把分片键的位运算结果编码进主键或异构索引表让非分片键也能反查出分片位置。3.2 归并的三种形态流式、内存、排序结果归并不是简单地把 List 拼起来。按 SQL 语义分三类归并类型触发场景实现要点遍历归并无排序、无聚合的普通查询逐条读取各分片结果直接追加排序归并带ORDER BY各分片结果需有序用优先队列做多路归并聚合归并COUNT/SUM/AVG/MAX/MINAVG需拆成SUM/COUNT再算不能直接平均AVG是最容易翻车的如果直接对各分片的平均值再求平均结果在分片数据量不均时完全错误。正确做法是改写为SUM(x)/COUNT(x)归并阶段分别累加再相除。这类改写逻辑在中间件里是硬编码的规则理解它你才知道为什么某些聚合查询在分片后结果对不上。3.3 分页的深坑LIMIT offset, size为什么要改写成LIMIT 0, offsetsize单库分页LIMIT 100000, 10只是扫描偏移分片后每个分片都要返回前100010条归并后再截取第100000到100010条。改写规则是把LIMIT offset, size改成LIMIT 0, offsetsize下发到各分片归并排序后再内存截断。数据量大时这个内存开销非常可观所以分片场景下的深分页要么禁用要么改用“上次最大 ID”的游标分页。这是设计取舍不是 bug。4. 避坑与排查多数据源分库分表最常见的五类翻车4.1 现象偶发读到别的租户/别的库的数据原因几乎总是 ThreadLocal 没清理线程池复用导致路由键残留。排查方法是打印determineCurrentLookupKey()的返回值并带上线程名观察同一线程连续两次请求的 key 是否异常。解决切面里用try-finally恢复旧值拦截器afterCompletion兜底clear()。4.2 现象Transactional方法里切换数据源无效原因是事务切面先于数据源切面执行连接已绑定。排查看两个切面的Order值或直接断点getConnection()的调用栈。解决把数据源切换移到事务方法外层或显式提高数据源切面优先级跨库写操作改用分布式事务方案别指望注解。4.3 现象异步线程里查到了默认库Async或手动new Thread不会继承父线程的 ThreadLocal。解决用TaskDecorator在任务提交时把路由键复制到子线程执行完清理或者干脆在异步任务入口显式set。4.4 现象分片后COUNT结果偏大或AVG不准COUNT偏大通常是全路由时重复统计了广播表AVG不准是归并阶段直接平均。排查看中间件是否把聚合函数下推改写。解决确认广播表配置正确聚合查询改用SUM/COUNT手工计算。4.5 现象启动后第一个请求特别慢连接池懒加载多数据源意味着多个池首次建连叠加。解决配置initialSize预热或在健康检查里主动getConnection()一次。这个不算故障但会让监控误报。5. 设计取舍分库分表不是性能银弹而是一场关于“查询自由度”的交易把多数据源和分库分表放在一起看会发现它们解决的是两个不同层次的问题多数据源是按业务或读写角色隔离连接分库分表是按数据量水平切分存储。前者靠路由键和连接池管理后者靠 SQL 解析改写和结果归并。两者叠加时复杂度不是相加而是相乘——一个跨数据源的分片查询既要选对库又要拆对表还要把结果拼对。我越来越倾向于一个判断分库分表真正卖给你的不是性能而是“写入扩展性”代价是牺牲查询自由度。一旦拆了非分片键查询、跨分片 JOIN、深分页、分布式事务全部变成需要额外设计的成本项。所以选型时先问三个问题数据量是否真的到了单库瓶颈通常是千万级行或写入 TPS 打满、分片键是否覆盖了 80% 以上的查询、团队是否愿意接受“某些查询就是查不了”的现实。如果答案是否定的读写分离加索引优化往往比拆库更划算。验证一套多数据源分库分表方案是否可靠我一般会做三件事压测时观察各分片连接池的活跃数是否均衡、用混沌手段杀掉一个分片看归并逻辑是否优雅降级、以及在事务方法里故意嵌套切换数据源看是否报错而不是静默串库。最后一条最能暴露设计缺陷——能报错的实现比能跑通的实现更值得信任。从那以后我每次配多数据源都强制先写一个“嵌套调用 异步线程 事务回滚”的冒烟用例跑一遍跑不过就不往下写业务。希望帮到你。本文还有配套的精品资源点击获取
简介这份资源面向需要掌握多数据源与分库分表技术的 Spring Boot 开发者聚焦同一数据库内水平分表与跨库分库两类场景解决单表数据膨胀、多数据源切换与读写路由等实际问题适合具备一定 Spring Boot 与 MyBatis 基础、希望进阶分布式数据访问的中级开发者。项目采用 Spring Boot 搭建多数据源基于 mybatis-plus 的 dynamic-datasource 实现分库分表由 sharding-jdbc 承担连接池选用 alibaba 的 druid-spring-boot-starter并继承 MyBatis-Plus 简化数据库操作、引入 Lombok 精简实体代码配合 JUnit 完成测试验证。压缩包共 162 个文件以 115 个 xml 映射与配置、14 个 java 源码、14 个 class 编译文件为主另有 6 个 yml、3 个 properties 等配置文件整体约 164KB结构紧凑便于按模块查阅。目前已有 624 人学习可帮助读者理解多数据源动态切换、分库分表规则配置与测试用例组织方式快速搭建可运行的示例工程并对照源码排查配置问题。1. 多数据源与分库分表为什么“加个注解就切换”往往是最危险的设计很多人第一次接触多数据源是从一个DS(slave)注解开始的——方法上标一下连接就切过去了看起来优雅得像魔法。但真正在生产里跑过一段时间的人会发现这套“注解即切换”的模型在事务、异步线程、嵌套调用、连接池预热这几个场景下会接连翻车。原因不复杂数据源切换的本质是在 ThreadLocal 里放一个路由键再由AbstractRoutingDataSource在getConnection()时读出来决定去哪个库而 ThreadLocal 的可见性边界恰好和事务传播、线程池复用、AOP 代理顺序全都对不上。Spring Boot 生态里做多数据源和分库分表的方案很多但底层机制就那么几层路由键的存放、连接的选择、事务的绑定、SQL 的改写与归并。把这几层拆开看你才会明白为什么有些配置“能跑但不可靠”也才知道分库分表真正难的不是拆而是拆完之后那条查询怎么拼回来。2. 路由机制AbstractRoutingDataSource到底在什么时候决定用哪个库2.1 路由键存在哪ThreadLocal 的可见性边界Spring 的AbstractRoutingDataSource继承自AbstractDataSource核心只有一个抽象方法determineCurrentLookupKey()。它在getConnection()被调用时执行返回值作为 key 去targetDataSources这个 Map 里找真正的DataSource。常见的实现思路是把路由键放进ThreadLocal因为一次请求内绝大多数数据库操作都发生在同一个线程上。public class DynamicDataSource extends AbstractRoutingDataSource { Override protected Object determineCurrentLookupKey() { // 从 ThreadLocal 取出当前线程绑定的数据源标识 return DataSourceContextHolder.get(); } } public final class DataSourceContextHolder { // 用 ThreadLocal 保存路由键线程隔离 private static final ThreadLocalString CONTEXT new ThreadLocal(); public static void set(String key) { CONTEXT.set(key); } public static String get() { return CONTEXT.get(); } // 用完必须清理否则线程池复用会串库 public static void clear() { CONTEXT.remove(); } }这段代码的关键不在set而在clear。ThreadLocal的生命周期跟着线程走而 Web 容器和业务线程池都会复用线程。如果一次请求结束时没有remove()下一个请求复用同一线程时读到的就是上一个请求残留的路由键——这就是最典型的“串库”事故。我一般会把这个清理动作放在拦截器的afterCompletion里并且用try-finally包住保证异常路径也能清掉。determineCurrentLookupKey()的调用时机也值得注意它不是在方法进入时调一次而是每次获取连接都会调。这意味着同一个事务里如果中途改了 ThreadLocal 的值后续拿到的连接可能来自另一个库——而事务已经绑定在第一个连接上了结果就是部分操作游离在事务之外。这是理解后面所有坑的前提。2.2 AOP 切面与事务的先后顺序谁包住谁注解式切换通常靠一个Around切面在方法执行前set、执行后clear。问题在于 Spring 的事务也是 AOP两个切面的顺序决定了行为。如果数据源切面在事务切面外层那么事务开启时路由键已经就位DataSourceTransactionManager拿到的连接来自正确的库如果顺序反了事务先开启、连接先绑定切面再改路由键就完全无效——方法里所有 SQL 还是走原来的库。常见的实现思路是给数据源切面显式指定Order(Ordered.HIGHEST_PRECEDENCE)让它比Transactional更早进入。但更稳妥的做法是不要在同一个方法上既开事务又切数据源而是把数据源切换放在事务方法的外层调用者上。因为一旦事务已经绑定连接中途换库在 JDBC 层面就是不成立的——一个Connection对应一个物理库跨库事务需要分布式事务框架不是切个注解能解决的。2.3 嵌套调用时路由键的覆盖问题假设方法 A 标了DS(master)内部调用方法 B 标了DS(slave)。如果切面是简单的set后clearB 执行完clear会把整个 ThreadLocal 清空回到 A 继续执行时路由键已经没了determineCurrentLookupKey()返回 null落到默认数据源——可能既不是 master 也不是 slave。正确的做法是保存旧值、执行、恢复旧值类似栈的语义Around(annotation(ds)) public Object around(ProceedingJoinPoint pjp, DS ds) throws Throwable { String previous DataSourceContextHolder.get(); // 记住外层路由键 try { DataSourceContextHolder.set(ds.value()); return pjp.proceed(); } finally { // 恢复而不是清空保证嵌套调用能回到外层数据源 if (previous null) { DataSourceContextHolder.clear(); } else { DataSourceContextHolder.set(previous); } } }这个细节在单层调用里完全看不出来一旦出现 Service 互相调用就暴露。血泪经验是凡是操作 ThreadLocal 的切面都要按“保存—修改—恢复”写而不是“设置—清空”。3. 分库分表的 SQL 改写一条SELECT是怎么被拆成 N 条再拼回来的3.1 解析、路由、改写、归并四步流水线分库分表中间件无论客户端模式还是代理模式处理一条 SQL 的流程基本固定SQL 解析 → 分片路由 → SQL 改写 → 结果归并。以SELECT * FROM t_order WHERE user_id 100 AND order_id IN (1,2,3)为例如果分片键是user_id路由阶段算出100落在ds_1.t_order_0改写阶段把表名替换成实际物理表归并阶段把结果集合并返回。难点在于分片键不在条件里。SELECT * FROM t_order WHERE order_id 5这种查询路由阶段无法定位到具体分片只能全路由——向所有分片各发一条 SQL再把结果归并。这就是为什么分库分表后“非分片键查询”会突然变慢不是数据库慢了是查询被放大成了 N 倍。常见的实现思路是引入基因法把分片键的位运算结果编码进主键或异构索引表让非分片键也能反查出分片位置。3.2 归并的三种形态流式、内存、排序结果归并不是简单地把 List 拼起来。按 SQL 语义分三类归并类型触发场景实现要点遍历归并无排序、无聚合的普通查询逐条读取各分片结果直接追加排序归并带ORDER BY各分片结果需有序用优先队列做多路归并聚合归并COUNT/SUM/AVG/MAX/MINAVG需拆成SUM/COUNT再算不能直接平均AVG是最容易翻车的如果直接对各分片的平均值再求平均结果在分片数据量不均时完全错误。正确做法是改写为SUM(x)/COUNT(x)归并阶段分别累加再相除。这类改写逻辑在中间件里是硬编码的规则理解它你才知道为什么某些聚合查询在分片后结果对不上。3.3 分页的深坑LIMIT offset, size为什么要改写成LIMIT 0, offsetsize单库分页LIMIT 100000, 10只是扫描偏移分片后每个分片都要返回前100010条归并后再截取第100000到100010条。改写规则是把LIMIT offset, size改成LIMIT 0, offsetsize下发到各分片归并排序后再内存截断。数据量大时这个内存开销非常可观所以分片场景下的深分页要么禁用要么改用“上次最大 ID”的游标分页。这是设计取舍不是 bug。4. 避坑与排查多数据源分库分表最常见的五类翻车4.1 现象偶发读到别的租户/别的库的数据原因几乎总是 ThreadLocal 没清理线程池复用导致路由键残留。排查方法是打印determineCurrentLookupKey()的返回值并带上线程名观察同一线程连续两次请求的 key 是否异常。解决切面里用try-finally恢复旧值拦截器afterCompletion兜底clear()。4.2 现象Transactional方法里切换数据源无效原因是事务切面先于数据源切面执行连接已绑定。排查看两个切面的Order值或直接断点getConnection()的调用栈。解决把数据源切换移到事务方法外层或显式提高数据源切面优先级跨库写操作改用分布式事务方案别指望注解。4.3 现象异步线程里查到了默认库Async或手动new Thread不会继承父线程的 ThreadLocal。解决用TaskDecorator在任务提交时把路由键复制到子线程执行完清理或者干脆在异步任务入口显式set。4.4 现象分片后COUNT结果偏大或AVG不准COUNT偏大通常是全路由时重复统计了广播表AVG不准是归并阶段直接平均。排查看中间件是否把聚合函数下推改写。解决确认广播表配置正确聚合查询改用SUM/COUNT手工计算。4.5 现象启动后第一个请求特别慢连接池懒加载多数据源意味着多个池首次建连叠加。解决配置initialSize预热或在健康检查里主动getConnection()一次。这个不算故障但会让监控误报。5. 设计取舍分库分表不是性能银弹而是一场关于“查询自由度”的交易把多数据源和分库分表放在一起看会发现它们解决的是两个不同层次的问题多数据源是按业务或读写角色隔离连接分库分表是按数据量水平切分存储。前者靠路由键和连接池管理后者靠 SQL 解析改写和结果归并。两者叠加时复杂度不是相加而是相乘——一个跨数据源的分片查询既要选对库又要拆对表还要把结果拼对。我越来越倾向于一个判断分库分表真正卖给你的不是性能而是“写入扩展性”代价是牺牲查询自由度。一旦拆了非分片键查询、跨分片 JOIN、深分页、分布式事务全部变成需要额外设计的成本项。所以选型时先问三个问题数据量是否真的到了单库瓶颈通常是千万级行或写入 TPS 打满、分片键是否覆盖了 80% 以上的查询、团队是否愿意接受“某些查询就是查不了”的现实。如果答案是否定的读写分离加索引优化往往比拆库更划算。验证一套多数据源分库分表方案是否可靠我一般会做三件事压测时观察各分片连接池的活跃数是否均衡、用混沌手段杀掉一个分片看归并逻辑是否优雅降级、以及在事务方法里故意嵌套切换数据源看是否报错而不是静默串库。最后一条最能暴露设计缺陷——能报错的实现比能跑通的实现更值得信任。从那以后我每次配多数据源都强制先写一个“嵌套调用 异步线程 事务回滚”的冒烟用例跑一遍跑不过就不往下写业务。希望帮到你。本文还有配套的精品资源点击获取
