MyBatis BaseMapper如何实现动态表名？

Question

在使用 MyBatis 的 BaseMapper（如继承自 MyBatis-Plus 的 BaseMapper）时，如何实现动态表名是一个常见难题。由于 BaseMapper 在启动时通过注解（如 `@TableName`）静态绑定实体类与表名，无法直接支持运行时切换表名（如按月分表、多租户场景）。开发者常问：能否在不修改源码的前提下，通过拦截器或 SQL 注入器动态修改 SQL 中的表名？如何结合 `DynamicTableNameParser` 或 `InnerInterceptor` 实现表名路由？同时保证 CRUD 操作正常调用？这涉及 MyBatis-Plus 的执行流程、SQL 解析时机与动态拼接机制，是实际项目中高频遇到的技术挑战。

Answer 1

一、MyBatis-Plus 动态表名实现机制深度解析

1. 问题背景与核心挑战

在使用 MyBatis-Plus 的 BaseMapper 时，实体类通常通过 @TableName("user_info") 注解静态绑定数据库表名。这种设计在启动期完成 SQL 映射构建，导致无法在运行时动态切换目标表（如按月分表：user_info_202401, user_info_202402），也无法支持多租户场景下的表隔离。

开发者常面临如下问题：

• 能否不修改 MyBatis-Plus 源码的前提下实现动态表名？
• 如何在 CRUD 操作中透明地替换实际执行的表名？
• SQL 解析发生在哪个阶段？能否在 SQL 构建前拦截并修改表名？

2. MyBatis-Plus 执行流程与 SQL 解析时机

理解动态表名的关键在于掌握 MyBatis-Plus 的内部执行流程：

1. 应用启动时，MyBatis-Plus 扫描所有标注 @TableName 的实体类。
2. 通过 GlobalConfiguration 和 SqlInjector 预生成通用 CRUD 的 SQL 片段（如 SELECT * FROM user_info）。
3. 这些 SQL 在首次调用 Mapper 方法时被缓存，后续复用。
4. 真正可干预的时机是在 SQL 实际执行前，由 Executor 触发拦截器链处理。

3. 动态表名的技术路径对比

方案	实现方式	是否侵入代码	支持 CRUD	适用场景
自定义 SQL + 参数传表名	XML 中使用 ${tableName}	高	部分	灵活但失去通用性
TableNameHandler（旧版）	已废弃，兼容性差	中	有限	历史项目迁移
DynamicTableNameParser	基于 SQL 解析树替换	低	全量	推荐方案
InnerInterceptor 修改 BoundSql	拦截 Executor 执行	低	全量	高级定制

4. 基于 DynamicTableNameParser 的实现方案

从 MyBatis-Plus 3.4.0 起引入了 DynamicTableNameParser，允许在 SQL 解析阶段动态替换表名。

public class DynamicTableNameConfig {

    @Bean
    public MybatisPlusConfig mybatisPlusConfig() {
        MybatisPlusConfig config = new MybatisPlusConfig();
        List<ISqlParser> sqlParserList = new ArrayList<>();
        
        DynamicTableNameParser dynamicTableNameParser = new DynamicTableNameParser();
        dynamicTableNameParser.setTableNameHandlerMap(new HashMap<String, ITableNameHandler>() {{
            put("user_info", (metaObject, sql, tableName) -> {
                String targetTable = TableRouteContext.getCurrentTable(); // 自定义上下文
                return targetTable != null ? targetTable : tableName;
            });
        }});
        
        sqlParserList.add(dynamicTableNameParser);
        config.setSqlParserList(sqlParserList);
        return config;
    }
}

5. 结合 InnerInterceptor 的高级控制

对于更复杂的路由逻辑（如基于 ThreadLocal 多租户、时间维度分片），可通过 InnerInterceptor 在执行前修改 BoundSql。

@Intercepts(@Signature(type = Executor.class, method = "query",
    args = {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class}))
public class TableNameInterceptor implements InnerInterceptor {

    @Override
    public void beforeQuery(Executor executor, MappedStatement ms, 
                           Object parameter, RowBounds rowBounds, ResultHandler resultHandler, 
                           BoundSql boundSql) throws SQLException {
        String originalSql = boundSql.getSql();
        String tenantId = TenantContext.getCurrentTenant();
        String dynamicTable = "user_info_" + tenantId;
        String modifiedSql = originalSql.replaceAll("user_info", dynamicTable);
        
        MetaObject metaObject = SystemMetaObject.forObject(boundSql);
        metaObject.setValue("sql", modifiedSql);
    }
}

6. 表名路由上下文设计模式

为保证线程安全与调用透明，应封装表名路由上下文：

public class TableRouteContext {
    private static final ThreadLocal<String> context = new ThreadLocal<>();

    public static void setCurrentTable(String table) {
        context.set(table);
    }

    public static String getCurrentTable() {
        return context.get();
    }

    public static void clear() {
        context.remove();
    }
}

7. 分月分表的实际应用场景示例

假设用户行为日志需按月分表（log_record_202401, log_record_202402...），可通过 AOP 或服务层前置设置：

@Service
public class LogRecordService {

    public List<LogRecord> getByMonth(int year, int month) {
        String table = String.format("log_record_%d%02d", year, month);
        TableRouteContext.setCurrentTable(table);
        try {
            return baseMapper.selectList(null); // 实际查询对应月份表
        } finally {
            TableRouteContext.clear();
        }
    }
}

8. 执行流程图：SQL 表名动态替换过程

graph TD
            A[Mapper方法调用] --> B{是否首次执行?}
            B -- 是 --> C[MP生成原始SQL]
            B -- 否 --> D[从缓存获取SQL]
            C --> E[DynamicTableNameParser介入]
            D --> E
            E --> F[根据上下文替换表名]
            F --> G[生成最终BoundSql]
            G --> H[Executor执行真实SQL]

9. 注意事项与性能考量

• 避免频繁创建和销毁 DynamicTableNameParser，应在 Spring 容器中单例管理。
• 正则替换表名时注意避免误匹配字段名或别名，建议精确匹配完整表标识。
• 使用 InnerInterceptor 时需确保不影响其他插件（如分页插件）的解析顺序。
• 动态表名可能导致执行计划缓存失效，需结合数据库连接池优化预编译策略。
• 建议配合表存在性校验机制，防止访问不存在的物理表引发异常。
• 在分布式环境下，表路由规则应统一配置中心管理，避免硬编码。
• 单元测试中需模拟不同路由场景，验证多表切换的正确性。
• 监控动态 SQL 生成数量，防止内存泄漏或元数据膨胀。
• 考虑使用 SQL 模板引擎（如 BeetlSQL）作为替代方案，在复杂场景下更具灵活性。
• 若涉及跨库分片，需结合 ShardingSphere 等中间件协同工作。

10. 总结性扩展：未来演进方向

随着云原生架构普及，数据分片与多租户成为标配能力。MyBatis-Plus 社区正在探索更原生的动态映射支持，例如：

• 支持注解表达式：@TableName("${tenant}.user")
• 集成 SPI 机制，允许外部注册表名解析策略。
• 与 Spring Expression Language (SpEL) 深度融合，实现运行时动态绑定。