简介围绕分库分表与多数据源切换的实战学习包面向已有一定 Java Web 与 MyBatis 基础、正面对单库数据膨胀和读写瓶颈的开发者和架构入门者。内容以 Sharding-JDBC 为主线串联分片策略与数据路由、跨库跨表事务一致性、多数据源配置与切换等关键问题并配合 SSMDemo 示例串联配置加载、数据源初始化到业务代码无侵入接入的完整链路可直接对照理解分片规则如何生效。压缩包共 73 个文件约 66KB以 18 个 Java 源码、18 个 XML 配置与映射文件、21 个 class 编译产物为主辅以 properties 配置、jsp 页面和一份 SQL 建表脚本目录沿用 Maven 标准结构导入 IDE 即可对照调试。该资源已有 2070 人学习下载可作为分库分表入门样例也便于排查分片规则配置与数据源切换中的常见问题。1. 分库分表之后谁来做那次“切库”——从一个订单查询偶发返回空说起分库分表真正落地的第一天麻烦往往不是出在拆表而是出在“切”明明 SQL 写对了结果却查不到数据。某公司的订单库单表涨到四千万行按 user_id 拆成 8 库 64 表上线第二周客服反馈“我的订单”页面偶发空白刷新一下又正常。日志里没有报错数据库里数据也在最后定位到一段异步补偿逻辑——主线程把分片键放进 ThreadLocal丢进线程池执行时上下文没带过去路由键为空落到了默认库默认表一次没有报错的错库查询。分库分表拆的是数据真正难的是每次访问数据前把连接切到正确的库上以及切完之后事务、分页、缓存、主从延迟这些老问题怎么重新兜住。这份资源就是围绕“切”做的一套工程骨架动态数据源注册、注解式切换、分片路由、强制走主、跨库事务兜底外加一套对账校验脚本。适合正在做单库拆多库的团队也适合已经拆完、但切换逻辑散落在各个 Service 里没人敢动的人。2. 先把路由讲清楚分片键、上下文与一次连接的归属2.1 分片键选错后面全是补丁分片键的选择不是“选一个查询条件”这么简单它同时决定了三件事数据分布是否均匀、单条业务查询能不能单片命中、以及未来扩容时数据要不要大搬迁。我一般的判断顺序是——先用业务上出现频率最高的查询条件做候选再检查这个条件的基数是否足够大最后看它是否会被更新。订单表最常见的选择是 user_id 和 order_id两者的差别不在均匀度而在你更愿意为哪一类查询付跨片成本。候选分片键分布均匀度单条查询命中主要跨片场景典型适用user_id高按用户查订单、订单列表全命中按订单号查详情C 端订单主表order_id高按订单号查详情全命中按用户查订单列表以单据详情为主的表create_time低热点集中在近期否任意时间范围查询归档表、流水表tenant_id取决于租户规模是大租户形成单库热点多租户 SaaSuser_id 做分片键的团队早晚会撞上“只有订单号、没有用户 ID”的入口比如支付回调、物流回传。这时候有两条路一条是维护一张 order_no 到 user_id 的索引表多一次查询另一条是基因法在生成订单号时就把分片信息嵌进去让订单号自己携带路由能力。前者多一跳但改动小后者零成本但要求订单号规则从第一天就设计好事后补是补不回来的。// 基因法把 user_id 的低位嵌进订单号让订单号本身可反推分片 public String genOrderNo(long userId, long seq) { // 取低 6 位正好对应 64 张表的表序号扩容到 128 时需要改这里 int gene (int) (userId 0x3F); // 秒级时间戳 2 位基因 6 位序列保证同一用户订单号前缀相同 return String.format(%d%02d%06d, System.currentTimeMillis() / 1000, gene, seq % 1_000_000); } // 反向解析从订单号直接拿到表序号不需要回查索引表 public int parseTableIndex(String orderNo) { return Integer.parseInt(orderNo.substring(orderNo.length() - 8, orderNo.length() - 6)); }这段代码的关键在0x3F和长度 8 这两个参数上。0x3F是 63 的十六进制取 user_id 的低 6 位所以分片数必须是 2 的幂如果库是 8 个、表是 64 张基因位就取到 6 位库序号再单独从 user_id 高位取。序列部分取模 100 万保证同一秒内同一用户不会重复实际生产里通常换成雪花算法或号段但位置和长度要保持不变否则历史订单解析不出来。这里最容易踩的坑是把基因位数和表数量写死在两个地方扩容时改了一处忘了另一处解析出来的表和实际写入的表对不上。分片键还有一个隐性约束尽量不要选会被更新的字段。订单的归属用户变更、订单从个人转企业这类需求一旦发生就意味着整行数据要跨库搬迁而跨库 UPDATE 在主流的客户端分片方案里是不支持的只能手动做“删旧插新”中间还要处理幂等和一致性问题。选键的时候多问一句“这个字段未来会不会变”能省掉后面很多血泪经验。2.2 路由上下文放在 ThreadLocal 里要用栈而不是单个变量决定“切到哪”的那个值通常放在 ThreadLocal 里因为一次请求内可能发生多次切换主流程走默认库调用某个服务切到订单库服务内部再切到库存库返回时要能回到订单库。如果只用一个普通变量保存当前数据源内层切完清空外层就丢了上下文后续 SQL 会静默落到默认库和开头那个案例一模一样。用栈结构可以自然地支持这种嵌套push 进去、poll 出来谁也别覆盖谁。public final class DataSourceContextHolder { // 用 Deque 而不是 String支持 A - B - A 的嵌套切换出栈即恢复 private static final ThreadLocalDequeString CTX ThreadLocal.withInitial(ArrayDeque::new); public static void push(String dsKey) { CTX.get().push(dsKey); } public static String peek() { DequeString deque CTX.get(); return deque.isEmpty() ? null : deque.peek(); } public static void poll() { DequeString deque CTX.get(); if (!deque.isEmpty()) { deque.poll(); } } // 线程池复用场景必须调用否则上一个任务的上下文会污染下一个任务 public static void clear() { CTX.remove(); } }peek返回 null 的时候不要直接当异常抛交给上层数据源去决定默认库是谁这样局部代码忘记标注也能跑只是跑在默认库上。真正要小心的是clearWeb 线程有请求边界finally里清一次就够但业务里只要用了线程池、CompletableFuture、消息消费线程ThreadLocal 就是跨任务共享的不清理会出现“上个请求查的是库 A这个请求莫名其妙也在库 A”。常见做法是包一层 Runnable 装饰器在任务提交和执行结束各做一次上下文快照与恢复或者统一换成支持上下文传递的 ThreadLocal 子类代价是每次传递都有一次拷贝。// 线程池提交任务时手动传递上下文执行完必须恢复现场 public T T submitWithContext(String dsKey, CallableT task) throws Exception { String outer DataSourceContextHolder.peek(); // 记录外层现场 DataSourceContextHolder.push(dsKey); try { return task.call(); } finally { DataSourceContextHolder.poll(); if (outer ! null) { DataSourceContextHolder.push(outer); // 恢复外层避免污染线程 } else { DataSourceContextHolder.clear(); } } }这段装饰逻辑看起来啰嗦但它解决的问题是真实存在的很多“偶发查不到数据”的工单最后都落在某段parallelStream或者自建线程池上。参数dsKey传的是数据源标识不是库名标识到物理连接的映射交给配置层去做这样改库地址不用动业务代码。2.3 一个能跑起来的最小骨架路由值有了接下来要有一个地方把它翻译成真正的连接。Spring 体系里最省事的做法是继承AbstractRoutingDataSource把多个真实数据源注册成 targetDataSources每次取连接时回调一次查找键。它的好处是不侵入 ORMMyBatis、JPA、JdbcTemplate 都能直接用坏处是它只在“取连接”这一刻生效一旦连接已经被事务绑定后面再怎么切都没用——这个边界在下一章会展开。public class DynamicDataSource extends AbstractRoutingDataSource { Override protected Object determineCurrentLookupKey() { String key DataSourceContextHolder.peek(); // 返回 null 时走 defaultTargetDataSource保证未标注的代码有兜底 return key; } } Configuration public class DataSourceConfig { Bean(master) ConfigurationProperties(prefix spring.datasource.master) public DataSource master() { // 每个数据源独立连接池池大小按该库的实际 QPS 单独调 return DruidDataSourceBuilder.create().build(); } Bean(orderDs) ConfigurationProperties(prefix spring.datasource.order) public DataSource orderDs() { return DruidDataSourceBuilder.create().build(); } Bean Primary public DataSource dynamicDataSource(Qualifier(master) DataSource master, Qualifier(orderDs) DataSource orderDs) { MapObject, Object targets new HashMap(); targets.put(master, master); targets.put(order, orderDs); DynamicDataSource ds new DynamicDataSource(); ds.setTargetDataSources(targets); ds.setDefaultTargetDataSource(master); // 默认库一定要设否则找不到键直接抛异常 return ds; } }这段配置有三个参数值得单独说。setDefaultTargetDataSource必须设不设的话查不到键会抛IllegalStateException而且是在运行期第一次取连接时才抛启动阶段看不出来。targets的 key 要和注解里写的值完全一致大小写不一样也算不同键这类问题排查起来非常费时间。每个数据源要独立配置连接池不要共用一个池的参数因为分片库的负载往往不均匀某个热点库的连接数打满不应该拖垮其他库。再往上一层把Primary标注在动态数据源上MyBatis 的SqlSessionFactory会自动注入它不需要额外改配置。如果项目里同时存在读写分离把从库也注册进 targetskey 用slave_0、slave_1这种形式负载均衡策略写在determineCurrentLookupKey里或者用独立的策略类不要让业务代码自己去挑从库。3. 三种切换姿势AOP 注解、AbstractRoutingDataSource、中间件代理3.1 注解加 AOP链路最短条件最苛刻业务代码里最舒服的写法是在方法上标一个注解切面负责压栈出栈。这套做法的链路只有三层注解解析、ThreadLocal 写入、数据源回调没有任何网络开销性能上基本可以忽略。但它对顺序极度敏感——切面必须比事务切面更早执行否则事务先开、连接先绑后面的切换就是无效操作。Target({ElementType.METHOD, ElementType.TYPE}) Retention(RetentionPolicy.RUNTIME) public interface DS { String value() default master; } Aspect Component Order(Ordered.HIGHEST_PRECEDENCE) // 必须小于事务切面的 order否则切了等于没切 public class DsAspect { Around(annotation(ds)) public Object around(ProceedingJoinPoint pjp, DS ds) throws Throwable { String key ds.value(); DataSourceContextHolder.push(key); try { return pjp.proceed(); } finally { DataSourceContextHolder.poll(); // 异常也要出栈否则线程被污染 } } }Order(Ordered.HIGHEST_PRECEDENCE)这个值是整段代码里最关键的一行。Spring 的事务切面默认 order 是Ordered.LOWEST_PRECEDENCE数值越大越靠后所以把数据源切面设成最高优先级它就会包在事务外层先切库再开事务。如果顺序反了现象是单测里切换生效一加Transactional就全走默认库而且不报任何错。这种“静默失效”比抛异常难查十倍因为它不会留下任何错误日志只能靠打印实际连接信息去确认。注解挂在类上还是方法上也要统一。挂在类上表示这个 Service 的所有方法默认走某个库方法上的注解覆盖类上的两者都没标时走默认库不报错。我倾向于要求团队里所有跨库调用必须显式标注不依赖默认值因为默认值一旦被改动受影响的范围是全局的而显式标注至少能在代码评审时被看见。3.2 determineCurrentLookupKey 的调用时机决定了它能被谁影响AbstractRoutingDataSource的getConnection()内部逻辑是先看当前线程有没有已绑定的事务连接有就直接返回没有才调用determineTargetDataSource()进而回调determineCurrentLookupKey()。也就是说路由只发生在“需要新拿一个连接”的时刻。理解这一点很多诡异现象就能解释通了。Service public class OrderService { Transactional public void createOrder(Order order) { // 事务开启时已经向默认库取过连接并绑定到线程此处执行的是默认库 orderMapper.insert(order); // 即便 deduct 方法上标了 DS(inventory)也不会生效 inventoryService.deduct(order.getSkuId(), order.getCount()); } } Service public class InventoryService { DS(inventory) public void deduct(Long skuId, Integer count) { // 期望走库存库实际仍在订单库连接上执行表不存在或数据查不到 stockMapper.decrease(skuId, count); } }这段代码的现象通常是“表不存在”或者“更新了 0 行”而不是明确的异常因为很多分片库的表结构是一致的SQL 能执行只是打在了错误的库上。原因就是事务连接已经被DataSourceTransactionManager绑定后续所有getConnection()都复用同一个。解决办法只有三种把跨库操作拆到事务外用REQUIRES_NEW开一个挂起当前事务的新事务或者干脆拆成两个服务、用消息做最终一致。第一种改动最小但要求业务能接受非原子第二种会占用两个连接且有死锁风险第三种最重但最干净。// 方案二挂起外层事务新开一个独立事务去拿库存库的连接 Transactional(propagation Propagation.REQUIRES_NEW, rollbackFor Exception.class) DS(inventory) public void deductInNewTx(Long skuId, Integer count) { stockMapper.decrease(skuId, count); }REQUIRES_NEW的代价是连接数翻倍如果外层事务持有行锁内层再去更新同一批数据很容易在压测时打出死锁。用之前先确认两件事内外事务操作的是不同库的不同表且内层执行时间足够短。不满足这两条宁可改成异步补偿。3.3 客户端分片和代理分片别在不该换的时候换选型阶段最容易吵起来的就是“要不要上代理”。客户端分片把路由逻辑放在应用里少一跳网络SQL 兼容性好缺点是升级要动所有应用、多语言支持差代理分片把路由放在独立进程里应用当单库用缺点是多了网络往返、复杂 SQL 支持有限、代理本身要高可用。两者没有绝对优劣只有阶段匹配。维度客户端分片代理分片网络开销无额外跳数每次查询多一次转发应用改造需要引入依赖、改配置基本只改连接串多语言支持弱通常只覆盖主流语言强任何能连数据库的都能用复杂 SQL支持较好可自行改写受代理解析能力限制扩容操作需配合数据迁移工具代理层统一处理运维复杂度低无额外组件高代理要集群化部署我的判断标准很朴素应用数量少于五个、技术栈统一优先客户端分片出问题能直接在应用日志里看到路由决策应用数量多、语言杂、或者有历史系统改不动再考虑代理。最怕的是两边都上一半一部分服务走客户端路由、一部分走代理同一个逻辑库有两套元数据排查问题时连“这条 SQL 到底打到哪个库”都说不清楚。4. 跨库之后的事务本地事务失效与最终一致的兜底4.1 同一个事务里切库为什么切不动本地事务能生效的前提是“一个事务一个连接”而分库分表之后一次业务操作往往要写多个库天然就不满足这个前提。很多人第一反应是“那我不用Transactional手动提交”结果发现部分成功、部分失败数据一半对一半错回滚都没法回。这个问题的本质不是框架不给力而是关系型数据库的本地事务边界就是单个连接跨连接要么两阶段提交要么放弃强一致。两阶段提交XA在分片场景里能用但不推荐原因是协调者日志、连接持有时间、以及部分数据库驱动对 XA 的支持并不完整一旦协调者在第二阶段挂掉悬挂事务需要人工介入。我见过的生产方案里XA 更多用在“同库不同表”或者“强一致要求极高的少量场景”绝大多数的跨库写入走的是最终一致。最终一致的落地形状通常是本地消息表加补偿。业务库和消息表在同一个库里本地事务保证两者一起成功或一起失败然后由独立线程或定时任务把消息投出去下游消费成功后回写状态失败就重试重试到上限进死信人工处理。这套模式的难点不在投递而在幂等——下游必须能识别重复消息否则重试会把库存扣两次。Transactional(rollbackFor Exception.class) public void createOrderWithMessage(Order order) { // 订单和消息在同一个库本地事务保证原子性 orderMapper.insert(order); OutboxMessage msg new OutboxMessage(); msg.setBizKey(order.getOrderNo()); // 业务唯一键下游据此做幂等 msg.setTopic(ORDER_CREATED); msg.setPayload(JSON.toJSONString(order)); msg.setStatus(0); // 0 待投递 1 已投递 2 消费成功 outboxMapper.insert(msg); } // 下游消费先查幂等表已处理直接返回成功不重复执行业务 public void onOrderCreated(OutboxMessage msg) { if (idempotentMapper.exists(msg.getBizKey(), ORDER_CREATED)) { return; } stockService.deduct(msg.getPayload()); idempotentMapper.insert(msg.getBizKey(), ORDER_CREATED); }这段代码里bizKey的选择比代码本身重要。用订单号做幂等键要求订单号在全局唯一基因法生成的订单号天然满足如果用的是数据库自增 ID跨库之后就不唯一了得换成雪花 ID 或者业务单号。status字段的三态设计是为了让补偿任务能区分“还没发出去”和“发出去了但没确认”扫描时只捞status 0且创建时间超过一定阈值的记录避免和正常投递线程抢同一批数据造成重复发送。4.2 补偿、幂等、对账最终一致的三件套补偿解决“失败之后怎么办”幂等解决“重试会不会重复”对账解决“我怎么知道有没有漏”。前两个是事前设计第三个是事后兜底很多团队只做前两个上线三个月后发现两边数据对不上又没有对账手段只能停机全量比对代价极大。对账的做法是每天凌晨按分片键抽样从业务库和下游库各取一批数据做比对差异写进差异表人工或者自动修复。抽样比例不用太高千分之一就够发现系统性问题关键是比对维度要选对金额、状态、数量这类强敏感字段必须比时间戳这种允许有秒级误差的字段不要比否则差异表会被噪音淹没。-- 按分片键取模抽样避免全表扫描比对订单金额与下游流水金额 SELECT o.order_no, o.amount AS order_amount, f.amount AS flow_amount FROM order_db_${shard}.t_order o JOIN flow_db_${shard}.t_flow f ON f.order_no o.order_no WHERE o.id % 1000 7 -- 抽样千分之一 AND o.create_time #{start} AND o.create_time #{end} AND o.amount f.amount;${shard}是分片占位符由调度任务按库表数量循环替换不要用UNION ALL拼一张大 SQL那样执行计划会退化成全表扫描凌晨跑一次能把数据库压垮。区间参数start和end建议取自然日跨天数据留给第二天的任务避免边界重复比对。4.3 读写分离主从延迟下怎么强制走主分库之后通常会带读写分离写主读从但主从复制有延迟刚写完立刻查可能查不到。这类问题在“下单后跳转详情页”这种链路上特别明显用户看到的是“订单不存在”。通用的做法是给注解加一个标记读操作默认走从库写完之后的一段时间内强制走主库或者提供DS(value master, forceMaster true)这样的显式声明。// 写后立即读显式指定主库绕过从库延迟 DS(value order, forceMaster true) public Order detailAfterCreate(String orderNo) { return orderMapper.selectByNo(orderNo); }强制走主不能滥用。如果所有读都标主库读写分离就白做了主库压力回到拆分前。合理的策略是只对“写后 N 秒内的读”生效用拦截器识别请求上下文里是否有写操作标记有就临时切主没有就走从。这个窗口期一般设 1 到 3 秒具体值取决于主从延迟的 P99压测时用SHOW SLAVE STATUS里的Seconds_Behind_Master观察不要凭感觉定。还有一个容易忽略的点是缓存穿透。分片之后缓存的 key 如果只用了订单号没带分片信息不同库的同号数据会互相覆盖。key 的规则最好和分片规则一致比如order:{userId % 64}:{orderNo}这样缓存和数据库的路由逻辑对得上排查时也能一眼看出该去哪个库找。5. 避坑与排查五个把线上打回滚的细节5.1 路由上下文丢失与线程复用污染现象单测和本地联调都正常上线后偶发查不到数据频率大概千分之几重启后消失过一段时间又出现。日志里同一条 SQL 有时走订单库有时走默认库。原因第一种可能是异步线程没有传递 ThreadLocal主线程的路由键在新线程里读不到返回 null 走了默认库第二种是线程池复用上一个任务执行完没清理上下文下一个任务继承了这个脏值。两者都表现为“随机走错库”但排查方式不同——前者看任务提交的调用链后者看线程名是否重复出现。解决所有跨线程提交都必须走统一的上下文传递装饰器禁止裸调executor.submitWeb 请求在Filter的finally里统一clear线程池配置里加一个自定义的RejectedExecutionHandler拒绝时顺带清理上下文。排查时在数据源回调里打一行日志输出线程名、路由键、调用栈前三层跑一天就能定位到具体位置。5.2 事务与切换的先后顺序错位现象加了Transactional的方法里调用另一个标了DS的方法目标库的表结构和默认库一致时表现为“更新了 0 行”不一致时抛“表不存在”。事务回滚日志正常看不出异常。原因Spring 的事务切面默认 order 值远大于自定义切面事务先开启并把连接绑定到线程后续getConnection全部复用determineCurrentLookupKey根本不会被回调。这是框架设计使然不是 bug。解决数据源切面的 order 必须显式设为Ordered.HIGHEST_PRECEDENCE确实需要在一个业务方法里跨库写入时用REQUIRES_NEW或者编程式事务把边界拆开更好的做法是把跨库调用挪到事务提交之后用事件监听或者消息驱动。上线前写一个集成测试断言两边的实际连接 URL 不同能挡住绝大多数顺序问题。5.3 分页查询跨片后的数量错乱现象订单列表分页第 1 页返回 10 条第 2 页只返回 6 条越往后越少总条数和实际对不上。原因分片后的LIMIT offset, size被下发到每个分片各自执行各分片返回自己那一段归并时再做一次截取。跨片排序字段如果不唯一同一条记录可能在多个分片被取到或者边界记录被跳过最终结果就是数量不对。解决分页必须带唯一排序键比如订单号并且改用“查 N 条再归并”的方式把offset size作为每个分片的上限归并后统一裁剪深分页场景直接改成游标翻页用上一页最后一条的排序键做WHERE条件。如果用的是中间件确认它是否支持归并分页不支持就只能自己在应用层做。5.4 分片键被更新导致的数据搬迁现象一条订单从个人账号转到企业账号更新之后再按新账号查询查不到按老账号查询反而能查到但数据已经不对。原因分片键参与路由UPDATE 分片键时中间件会把它当成一次“在旧分片找不到、在新分片不存在”的更新不同实现对这类语句的处理不一致有的直接拒绝有的静默影响 0 行。解决设计阶段就把分片键列为不可变字段业务上确实需要变更归属时走“新增一条 逻辑删除旧记录”的路径用状态字段标记而不是物理 UPDATE 分片键。如果历史数据已经乱了写一个按新键重算的迁移脚本先写新记录、校验通过后再删旧记录中间保留双读一段时间。5.5 二级缓存跨数据源串数据现象同一个订单号在 A 库里查出来的金额和 B 库不一样但页面展示时偶尔会串。原因MyBatis 的二级缓存作用域是namespace不区分数据源。如果两个库共用同一个 Mapper 接口、同一个 namespace缓存 key 只由 SQL 和参数决定不同库的查询结果会命中同一份缓存。解决分片场景下直接关掉二级缓存只保留一级缓存会话级天然隔离确实需要缓存就上 Rediskey 里带库表标识。这个坑不常遇到但一旦遇到极难复现因为取决于哪次查询先填充缓存。6. 验证与压测怎么证明切换真的生效了切换逻辑写完不等于生效必须能被观测到。我习惯在数据源回调里埋一个计数器按“路由键 实际连接 URL”两个维度打点跑一轮回归后看分布如果某个注解标了order但计数全落在master上说明切换没生效如果两个键指向同一个 URL说明配置里的 key 写重了。这套指标比日志更直观也适合接到监控上做长期巡检。Override protected Object determineCurrentLookupKey() { String key DataSourceContextHolder.peek(); // 打点路由键 线程名用于验证切换是否真的发生 Metrics.counter(ds.route, key, String.valueOf(key)).increment(); return key; }压测阶段重点看三个数单库连接池的活跃连接数是否随分片均匀分布、跨库调用的 P99 是否显著高于单库、以及补偿任务的积压量。前两个反映路由正确性第三个反映最终一致的链路是否通畅。我一般会故意把某个分片的地址配错观察熔断和降级是否符合预期这种“主动制造故障”的验证比正常压测更能暴露问题。还有一个具体技巧用影子库做切换回归。把生产库的结构同步一份到影子库在测试环境把路由键指向影子库跑一遍全量接口对比两边返回。影子库的好处是不污染真实数据也不依赖造数脚本能覆盖到那些“只有线上才有”的边界数据。代价是要维护一套同步机制表结构变更时需要同步更新。从那以后我每次做分库分表改造都会强制走一遍“埋点验证 影子库回归 单分片故障演练”这三步哪怕工期再紧也不跳过因为切换类问题的共同点就是静默——它不报错只是把数据放错地方等到发现时往往已经积累了几个月。希望帮到你。本文还有配套的精品资源点击获取
