MyBatis-Plus XML SQL如何避免自动拼接租户？

Question

在使用 MyBatis-Plus 实现多租户功能时，常通过配置租户插件实现自动 SQL 拼接 tenant_id。但在某些场景下（如系统管理查询所有租户数据），需在 XML 定义的 SQL 中禁用自动拼接。问题在于：**当使用 XML 自定义 SQL 时，MyBatis-Plus 仍会默认触发租户拦截器，导致无法查询跨租户数据或出现 WHERE 条件冲突**。如何针对特定 XML SQL 精准关闭租户字段自动注入，成为关键难题。

Answer 1

一、背景与问题引入

在现代 SaaS 架构系统中，多租户（Multi-Tenant）已成为一种主流设计模式。MyBatis-Plus 提供了便捷的 租户插件（TenantLineInnerInterceptor），通过拦截 SQL 并自动拼接 tenant_id = ? 条件，实现数据隔离。

然而，在实际开发中，存在一些特殊场景——例如系统管理员需要跨租户查看汇总数据、审计日志或进行全局统计分析时，必须绕过租户隔离机制，查询所有租户的数据。

当使用 XML 自定义复杂 SQL 时，MyBatis-Plus 的租户拦截器仍会默认生效，导致以下问题：

• SQL 中已手动处理 tenant_id 过滤逻辑，但框架再次注入，造成 WHERE 条件重复；
• 本应查询全量数据的接口因自动拼接 tenant_id 而返回空结果；
• 动态 SQL 场景下条件冲突，引发 SQL 语法错误或逻辑异常。

二、核心原理剖析：租户拦截器工作机制

MyBatis-Plus 的多租户功能基于 InnerInterceptor 拦截器链实现，其中 TenantLineInnerInterceptor 在 SQL 解析阶段介入，通过 AST（抽象语法树）修改原始 SQL。

其执行流程如下所示（Mermaid 流程图）：

graph TD
    A[执行Mapper方法] --> B{是否启用租户拦截器?}
    B -- 是 --> C[解析SQL类型: SELECT/UPDATE/DELETE]
    C --> D[检查是否忽略租户注解 @IgnoreTenant]
    D -- 否 --> E[自动注入 tenant_id = currentTenantValue]
    D -- 是 --> F[跳过注入]
    E --> G[执行最终SQL]
    F --> G
    

关键点在于：该拦截器默认对所有 SQL 生效，除非显式标记“忽略”。

三、常见解决方案对比分析

方案	实现方式	适用范围	优点	缺点
1. 全局关闭 + 手动添加	不启用租户插件，业务层自行控制	灵活但风险高	完全可控	易遗漏，安全性差
2. 使用 @SqlParser(filter = true)	在 Mapper 方法上添加注解	适用于注解式 SQL	简单直接	XML 中无效
3. 自定义注解 + 拦截器判断	扩展 TenantLineInnerInterceptor 判断方法级别注解	通用性强	可精准控制	需二次开发
4. SQL 中使用 /* !TENANT */ 特殊注释	约定注释格式触发忽略逻辑	适合 XML 场景	无需改代码	依赖团队规范

四、推荐实践：基于自定义注解和拦截器增强的精准控制

为解决 XML 场景下无法关闭租户注入的问题，建议采用“注解驱动 + 增强拦截器”的策略。

步骤如下：

1. 定义一个自定义注解 @IgnoreTenant，用于标识无需租户过滤的方法；
2. 重写 TenantLineInnerInterceptor 的 beforeQuery 方法，加入注解判断逻辑；
3. 在对应的 Mapper 方法上标注该注解，即使使用 XML SQL 也可生效。

示例代码：

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface IgnoreTenant {
}
    

@Component
public class CustomTenantInterceptor extends TenantLineInnerInterceptor {

    @Override
    public void beforeQuery(Executor executor, MappedStatement ms, Object parameter) {
        // 获取当前执行的方法
        BoundSql boundSql = ms.getBoundSql(parameter);
        if (isIgnoreTenant(ms.getId())) {
            // 临时移除租户值
            StoreTenantId.set(null); 
        }
        super.beforeQuery(executor, ms, parameter);
    }

    private boolean isIgnoreTenant(String mappedStatementId) {
        try {
            String className = mappedStatementId.substring(0, mappedStatementId.lastIndexOf("."));
            String methodName = mappedStatementId.substring(mappedStatementId.lastIndexOf(".") + 1);
            Class<?> mapperClass = Class.forName(className);
            Method[] methods = mapperClass.getMethods();
            for (Method method : methods) {
                if (method.getName().equals(methodName) &&
                    method.isAnnotationPresent(IgnoreTenant.class)) {
                    return true;
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
        return false;
    }
}
    

五、高级技巧：结合 MyBatis 执行上下文动态控制

进一步优化可通过 ThreadLocal 存储上下文状态，实现更细粒度的运行时控制。

例如：

• 在 Service 层开启“忽略租户”模式；
• 调用完特定查询后恢复；
• 避免污染其他并行请求。

结合 Spring AOP 可实现自动化切面管理，提升代码整洁性。

典型应用场景包括：

1. 后台报表导出；
2. 跨租户数据迁移任务；
3. 运营平台全局搜索功能；
4. 定时批处理 job；
5. 调试模式下的全量数据预览；
6. 权限审批流中的历史记录追溯；
7. 多维度 BI 分析查询；
8. 租户合并/拆分操作；
9. 数据一致性校验脚本；
10. 灰度发布期间双写比对。