MyBatis拦截器实现动态表名与分库分表路由

本文深入剖析了如何通过 MyBatis 拦截器在 `StatementHandler.prepare` 这一关键且安全的切入点，精准、稳定地实现动态表名替换与分库分表路由——避开预编译陷阱，采用上下文感知的正则提取+白名单校验防误替换，借助反射安全修改 `BoundSql` 私有 SQL 字段并及时恢复访问控制，同时强调以 `ThreadLocal` 可靠传递分片键、严格 `clear()` 防止线程污染，真正解决从 Controller 到拦截器的分片上下文无感透传难题，直击生产环境中动态路由最易踩坑的核心细节。

拦截 StatementHandler.prepare 是最稳的切入点

MyBatis 执行 SQL 的关键链路中，StatementHandler.prepare(Connection, Integer) 是 SQL 已完成解析、参数尚未绑定、但 SQL 字符串仍可安全修改的最后窗口。此时 BoundSql.sql 是原始语句（含逻辑表名），且未进入 JDBC 预编译阶段，改表名不会破坏参数占位符结构。

选错拦截点会导致问题：拦截 Executor.query 时 SQL 已被预编译，无法直接替换；拦截 ParameterHandler 则根本拿不到完整 SQL 字符串。

• 必须用 @Intercepts(@Signature(type = StatementHandler.class, method = "prepare", args = {Connection.class, Integer.class}))
• 避免拦截 update 或 query 方法本身——那些是重载方法，args 容易配错导致拦截失效
• 不要在 plugin() 方法里做表名替换逻辑，它只负责代理包装，不参与执行流程

正则匹配表名要防误伤，别只靠单词边界

常见写法 Pattern.compile("(from|into|update)\\s+(\\w+)") 看似简洁，但极易误匹配：比如字段名叫 user_name、子查询里的 from temp、甚至注释中的 /* from backup */ 都会被抓取。

真正安全的做法是先提取完整的表名 token，再结合上下文判断是否为主表。推荐分两步：

• 用更精确的正则捕获 from / join / update 后紧跟的首个非括号标识符，例如：Pattern.compile("(?i)(?:from|join|update)\\s+([a-zA-Z_][a-zA-Z0-9_]*)")
• 拿到匹配出的候选名后，检查它是否在你声明的「逻辑表白名单」里（如 ["user", "order", "log"]），不在名单内就跳过替换
• 绝对不要对 insert into user select ... 这类语句里的第二个 user（即 select 子句中的）做替换

表名替换必须走反射 + setAccessible，不能只改 BoundSql 持有者

BoundSql 是个不可变对象，其内部 sql 字段通常是 final 或私有，直接调 boundSql.getSql().replace(...) 没用——改的是副本，原对象不受影响。

正确做法是通过反射强行修改其内部字段：

• 用 MetaObject.forObject(boundSql) 获取元对象，再 metaObject.setValue("sql", newSql) ——但部分 MyBatis 版本中该字段名是 sqlSource 或封装在 StaticSqlSource 里，不稳定
• 更通用可靠的方式是反射获取 BoundSql 的 sql 字段（注意不同版本字段名可能为 sql 或 sqlString），然后 field.setAccessible(true); field.set(boundSql, newSql)
• 替换完成后务必调用 field.setAccessible(false) 恢复访问限制，避免被其他代码误用

线程隔离必须用 ThreadLocal，别依赖方法参数传值

分表路由依赖运行时上下文（如当前用户 ID、时间戳、租户编码），这些值不可能从 Invocation 或 MappedStatement 里稳定提取——它们藏在 DAO 方法参数、HTTP 请求头、或 Spring Security Context 中。

所以必须由业务层提前把分片键注入线程上下文，拦截器只负责读取：

• 定义 TableNameContext 类，用 ThreadLocal CURRENT_TABLE_NAME 存储当前应路由到的物理表名
• 在 Service 层或 AOP 切面中，根据入参（如 @ShardTable(shardKey = "userId")）计算出物理表名，调 TableNameContext.set("user_2")
• 拦截器中仅做 String target = TableNameContext.get(); if (target != null) { ... }，用完立刻 TableNameContext.clear()
• 漏掉 clear() 会导致线程复用时脏数据污染后续请求，这是线上最常踩的坑

真正的难点不在替换逻辑本身，而在于如何让分片键从 Controller 层无感地流到拦截器——这要求你在注解设计、AOP 触发时机、以及 ThreadLocal 生命周期清理上都保持高度一致，任何一环脱节都会导致路由失效或错表查询。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《MyBatis拦截器实现动态表名与分库分表路由》文章吧，也可关注golang学习网公众号了解相关技术文章。