MyBatis-Plus 动态分表实战：基于 DynamicTableNameInnerInterceptor 的多端数据隔离方案

MyBatis-Plus 动态分表实战：基于 DynamicTableNameInnerInterceptor 的多端数据隔离方案

一、概述

本文基于MyBatis-PlusDynamicTableNameInnerInterceptor实现动态分表，核心思路是：在 SQL 执行前，通过 ThreadLocal 传递表名后缀，拦截器自动将逻辑表名替换为物理表名，从而实现多端数据隔离（如端 At_product_a、端 Bt_product_b）。

二、核心类职责

以上类名均为示意，实际项目中按自身命名规范调整。

三、调用链路

业务方法 → setShardType(type) → ShardContextHelper.setShardSuffix(suffix) ↓ (ThreadLocal 存储) MyBatis 执行 SQL ↓ DynamicTableNameInnerInterceptor 拦截 ↓ TableNameShardHandler.dynamicTableName(sql, tableName) ↓ ShardContextHelper.getShardSuffix() ↓ tableName + "_" + suffix → 实际物理表名 ↓ 业务方法 finally → clearShardType()

四、各层详细逻辑

4.1 配置层 —ShardInterceptorConfig

@Bean("shardingMybatisPlusInterceptor")publicMybatisPlusInterceptormybatisPlusInterceptor(){MybatisPlusInterceptorinterceptor=newMybatisPlusInterceptor();DynamicTableNameInnerInterceptordynamicTableNameInnerInterceptor=newDynamicTableNameInnerInterceptor();dynamicTableNameInnerInterceptor.setTableNameHandler(newTableNameShardHandler());interceptor.addInnerInterceptor(dynamicTableNameInnerInterceptor);returninterceptor;}

• 创建DynamicTableNameInnerInterceptor，设置全局唯一的TableNameShardHandler
• 该拦截器会拦截所有 SQL，对每张表都调用 Handler

4.2 拦截层 —TableNameShardHandler

@OverridepublicStringdynamicTableName(Stringsql,StringtableName){returntableShard(tableName);}publicStringtableShard(StringtableName){Stringsuffix=ShardContextHelper.getShardSuffix();if(ObjectUtil.isNotEmpty(suffix)){returntableName+"_"+suffix;}returntableName;}

• 从 ThreadLocal 读取后缀，非空则拼接原表名_后缀
• 后缀为空时原样返回，即不设置后缀的查询走原表

4.3 上下文传递层 —ShardContextHelper

privatestaticThreadLocal<String>shardSuffix=newThreadLocal<>();publicstaticvoidsetShardSuffix(Stringsuffix)// 设置publicstaticStringgetShardSuffix()// 获取publicstaticvoidclearShardSuffix()// 清除

• 使用ThreadLocal保证线程隔离，不同请求可路由到不同分表
• 提供 set/get/clear 三段式操作

4.4 配置属性层 —ShardTableProperties

privateStringtableTypes="a,b";// 支持的分表类型privateStringdefaultType="a";// 默认后缀

• defaultType：默认后缀为"a"，即未指定 type 时默认查端 A 分表
• tableTypes：声明了支持的分表类型列表

五、业务使用模式

所有业务类遵循统一的try-finally 模式：

publicList<XxxResponse>someMethod(Stringtype){try{// 1. 确定后缀：未传则用默认值if(StringUtils.isBlank(type)){type=shardTableProperties.getDefaultType();}// 2. 设置 ThreadLocalsetShardType(type);// 3. 执行数据库操作（此时 SQL 中的表名已被拦截器替换）...}finally{// 4. 清除 ThreadLocal，防止线程复用导致污染clearShardType();}}

适用场景示例

六、分表效果示例

假设逻辑表名为t_product：

七、设计特点

1. 线程安全：基于 ThreadLocal，每个请求线程独立，互不干扰
2. 对业务代码侵入小：只需在业务方法前后 set/clear，Mapper 层无感知
3. 灵活路由：通过请求参数动态决定查哪张分表，支持多端数据隔离
4. 防御性编程：finally 块确保 ThreadLocal 清除，避免线程池复用污染

八、潜在问题

8.1 全局拦截无差别替换

DynamicTableNameInnerInterceptor会对所有表执行 Handler，包括不需要分表的表。当 ThreadLocal 有值时，所有表名都会被拼接后缀，若某张表不存在对应的分表则会报错。当前依赖"不设后缀则不替换"来规避，但一旦忘记 clear 或在嵌套调用中设置，可能误伤其他表。

8.2 异步线程丢失上下文

如果业务方法中使用了CompletableFuture异步并发查询，子线程无法继承父线程的 ThreadLocal 值。若主线程未设置分表后缀就提交了异步任务，子线程中的查询可能走错表或走原表。

8.3 set/clear 重复散落

每个业务类都重复编写了setShardType()/clearShardType()方法，且 try-finally 模板代码大量重复，可抽取为模板方法或 AOP 切面统一管理。

8.4 命名规范

方法名中 “Shard” 拼写需统一（Shard = 分片），避免 “Shading”（阴影）等拼写错误混入。