一次「查到别家门店订单」的线上事故:Spring Boot 3 + MyBatis-Plus 多租户隔离踩坑复盘

一、背景:不是功能坏了,是边界破了

维护的是一套多门店 SaaS 后端:Java 17 + Spring Boot 3.5 + MyBatis-Plus,基于 RuoYi-Vue-Plus 的多租户架构,共享库、共享表,靠 tenant_id 做行级隔离。上线大半年一直正常,直到某天运营反馈:A 门店的店员在「订单导出」里看到了不属于自己门店的订单号。

这类问题最麻烦的地方在于,功能没坏、接口没报错、没有慢查询告警,只是数据边界悄悄破了。而且它不会稳定复现------列表页一切正常,只有导出偶尔出问题,很容易被当成「缓存没刷」糊弄过去。这篇把排查路径、修复代码、以及那些「没有 HTTP 请求」的旁路场景完整复盘一遍。

二、定位:从一条少了条件的 SQL 开始

排查只用了三步:

  1. 排除前端:抓请求,门店筛选参数正常,分页参数正常。
  2. 看真实 SQL :临时打开 SQL 日志(mybatis-plus.configuration.log-impl: org.apache.ibatis.logging.stdout.StdOutImpl,生产建议用 p6spy),分别复现「订单列表」和「订单导出」。列表那条打印出来带 AND tenant_id = 1001;导出那条完全没有 tenant_id 条件。
  3. 找差异 :列表走同步请求线程,导出走 @Async 线程池。租户 ID 由登录拦截器写入 ThreadLocal,异步线程读不到 → getTenantId() 拿不到值 → 插件没能追加过滤条件 → 全表。

根因一句话:租户上下文的生命周期,和 SQL 执行的生命周期没有对齐。

这里有个很容易被忽略的设计细节:租户插件不是黑盒,它每次改写 SQL 都会回调 TenantLineHandler.getTenantId()。拿不到租户 ID 时,它不会抛异常告诉你「上下文丢了」,而是可能拼出错误条件、也可能不再追加任何条件------无论哪种,业务侧看到的都是一个「成功」的查询结果。这种静默放行 才是最危险的部分。同轮排查还发现 Redis 缓存 key 写成 order:detail:{id},没带租户维度,是第二个潜在越权点,两个问题叠加才让现象时隐时现。

三、正确配置:把「静默放行」改成「显式失败」

先说一个前置坑:Spring Boot 3 要引 mybatis-plus-spring-boot3-starter,继续用老 starter 会出现插件不生效或启动报错,排查起来很费时间。

核心配置如下:

java 复制代码
@Configuration
public class MybatisPlusConfig {

    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();

        // 官方建议的功能顺序:多租户/动态表名类在前,分页/乐观锁在后。
        // 顺序别随手调整,count 语句与联表改写会受影响。
        interceptor.addInnerInterceptor(new TenantLineInnerInterceptor(new TenantLineHandler() {

            /** 系统表白名单:收敛式维护,别漏也别多 */
            private static final Set<String> IGNORE = Set.of(
                "sys_tenant", "sys_user", "sys_role", "sys_menu",
                "sys_dict_type", "sys_dict_data", "sys_config");

            @Override
            public Expression getTenantId() {
                Long tenantId = TenantContext.get();
                if (tenantId == null) {
                    // 关键:不要让空上下文静默通过
                    throw new IllegalStateException(
                        "租户上下文缺失,拒绝执行无租户条件的 SQL");
                }
                return new LongValue(tenantId);   // 返回 Expression,不是字符串
            }

            @Override
            public String getTenantIdColumn() {
                return "tenant_id";
            }

            @Override
            public boolean ignoreTable(String tableName) {
                return IGNORE.contains(tableName.toLowerCase());
            }
        }));

        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}

TenantContext 自己封装,别直接依赖 RequestContextHolder(它绑 Servlet 容器,在异步线程、定时任务、MQ 消费线程里一定丢):

java 复制代码
public final class TenantContext {
    // 线程池场景需要透传时可换 TransmittableThreadLocal(com.alibaba:transmittable-thread-local)
    private static final ThreadLocal<Long> HOLDER = new ThreadLocal<>();

    private TenantContext() {}
    public static void set(Long id)  { HOLDER.set(id); }
    public static Long get()        { return HOLDER.get(); }
    public static void clear()      { HOLDER.remove(); }
}

用 RuoYi-Vue-Plus 的话,租户 ID 可从 LoginHelper / TenantHelper 取,注意它们的返回类型与这里的 Long 需要转换;关键是别在 getTenantId() 里查库或发 HTTP,这个方法每次执行 SQL 都会被调用,放 IO 等于给每条 SQL 加一次远程调用。

异步入口显式透传,并且一定在 finally 里清理:

java 复制代码
@Async
public void exportOrders(Long tenantId, OrderQuery query) {
    TenantContext.set(tenantId);            // 别指望父线程上下文自动过来
    try {
        List<OrderInfo> list = orderMapper.selectList(buildWrapper(query));
        // ... 写 Excel
    } finally {
        TenantContext.clear();             // 线程会被复用,不清就串租户
    }
}

定时任务按租户逐个切换,同样是 set / clear 成对出现:

java 复制代码
for (Long tenantId : tenantMapper.listEnabledTenantIds()) {
    TenantContext.set(tenantId);
    try {
        closeExpiredOrders(tenantId);
    } finally {
        TenantContext.clear();
    }
}

缓存 key 补上租户维度,别让缓存层绕过 DB 的隔离:

java 复制代码
// 错误:order:detail:{id}
String key = "order:detail:" + TenantContext.get() + ":" + orderId;

四、最容易漏的六个场景

1. 异步线程 / @Async / 自定义线程池。 本次事故根因。除了在每个入口显式 set,更省心的做法是给线程池配一个 TaskDecorator,在任务提交时快照父线程上下文、执行前恢复、执行后清理,避免靠人记得写。

2. 定时任务、MQ 消费、XXL-Job。 没有请求头、没有登录态、没有拦截器,上下文天然是空的。必须显式按租户循环切换;多租户批量处理时尤其注意 clear(),否则上一个租户的 ID 会留到下一轮。

3. XML 手写 SQL 与联表别名。 插件基于 JSqlParser 做 AST 改写,复杂子查询、INSERT ... SELECT、REPLACE INTO 一类语句可能改不到或改得不符合预期。这类要么显式把 tenantId 传进 SQL,要么先 ignoreTable 兜底再手写条件,并把「自定义 SQL 清单」写进代码规范,上线前逐条过。

4. @InterceptorIgnore(tenant = "true")。 它只对当前线程、当前方法生效,别当成全局开关用。更要紧的是:忽略之后 SQL 不再自动拼租户条件,忘了显式传 tenant_id 就是全表泄露 。超管跨租户查询建议收敛到一个专门的 AdminService,显式传参 + 记审计日志,不要让这个注解散落在各个 Controller 里。

5. 缓存、消息队列、导出文件。 这些链路根本不经过 SQL 拦截器,DB 层隔离得再好也管不到。凡是带业务 ID 的 key / topic / 文件名,都把租户维度带上。

6. 插件顺序与忽略表白名单。 白名单要「收敛」而不是「随手加」,多放行一张业务表就是一处越权;漏放行系统表则会导致管理员连登录都查不到用户。getTenantId() 里禁止任何 IO。

另外两条架构级边界值得提前想清楚:

  • 用了动态数据源按租户分库,就别再叠行级过滤插件,两套逻辑会互相打架。
  • tenant_id 在实体、DB 字段、请求头三处类型统一(都用 Long),否则隐式转换会让联合索引失效;索引建议按 (tenant_id, 高频查询条件) 建。

五、方案对比:隔离到底放在哪一层

方案 优点 代价 / 适用边界
每个查询手写 where tenant_id = ? 最可控,SQL 一目了然 人一定会漏;条件散落各处,无法统一审计,一处漏就是事故
MyBatis-Plus TenantLineInnerInterceptor 零侵入、统一收口、业务代码干净 复杂 SQL 覆盖不全;上下文必须自己管好;不适用于分库/跨库场景
数据库 RLS / 视图 隔离落在存储层,应用怎么写都漏不出去 运维与调试成本高,云托管实例支持程度不一,权限模型变更麻烦
分库 / 分 schema + 动态数据源 隔离最强,单库故障域小 迁移、跨租户统计、连接池与运维成本明显上升

对绝大多数共享库共享表、SQL 以 CRUD 为主、单租户数据量中等 的中小 SaaS,我的推荐很明确:MyBatis-Plus 租户插件 + 一套显式的上下文治理规范,性价比最高,改造成本也最低。但请把「上下文治理」当成项目规范来建设(线程池装饰器、定时任务模板、代码评审 checklist),而不是当成插件的默认能力------这正是这次事故的教训。

什么时候该换方案?当单表数据量上来、出现大量跨租户分析需求,或者客户提出数据物理隔离的合规要求时,再评估分库 / RLS。一开始就上分库,通常是用运维复杂度换一个还不存在的规模问题。

六、验证方式与上线 checklist

不要靠「点一下看着对」来验证权限边界,用可复现的断言:

  • 单测 :切到租户 A 执行一条查询,用 SQL 日志或自定义拦截器断言生成语句里带 tenant_id = A;再断言上下文为空时按配置抛异常,而不是放行。
  • 交叉验证:造两个租户各若干条订单(示例数据),分别登录,断言列表、详情、导出、缓存四条链路都只能看到自己的数据。导出这次事故就是这么被固定下来的。
  • 上线 checklist :所有 @Async / 定时任务 / MQ 入口是否 set+clear;缓存 key 是否带租户;忽略表白名单是否评审;超管跨租户查询是否收敛并审计;XML 自定义 SQL 是否逐条确认。
  • 监控兜底:把「租户上下文为空却执行了 SQL」打成 ERROR 日志并配告警,别让它继续静默。

这里不贴压测数字,索引收益与数据量、字段类型、SQL 形态强相关,自己用 EXPLAIN 看执行计划比引用别人的表格靠谱得多。

七、总结

  • 插件是「帮你拼条件」,不是「帮你管上下文」;拿不到租户 ID 时它默认不报错,建议改成显式抛异常。
  • 事故往往不在主流程,而在异步、定时、缓存这些没有 HTTP 请求的旁路。
  • 忽略表白名单要收敛,@InterceptorIgnore 要收敛到专门服务并审计;忽略后必须显式传 tenant_id。
  • 插件顺序、系统表白名单、tenant_id 类型一致性,是三个不起眼但一定要在评审里过一遍的点。
  • 选型:共享库共享表的中小 SaaS 首选 TenantLineInnerInterceptor;SQL 复杂度高或有合规隔离要求时再上 RLS / 分库,别提前过度设计。

建议标签 :多租户、MyBatis-Plus、Spring Boot、RuoYi-Vue-Plus、线上故障复盘

CSDN 分类建议:主投「后端开发 / Java」,也可投「数据库 / 数据安全」。文章类型选「原创」,不勾选任何推广或转载选项。

相关推荐
学长毕设15 小时前
基于SpringBoot智慧养老服务平台设计与实现-附源码
java·spring boot·后端
千寻技术帮17 小时前
10454_基于Springboot的企业购销链管理系统
spring boot·mysql·vue·毕业设计·进销存
Forget the Dream17 小时前
Spring AI 2.0 系列(二):第一个 ChatClient——从注入到一次完整调用
java·人工智能·spring boot·ai·springai
她的男孩20 小时前
设计器能拖抄送,一点发布却报 flowable-servicetask-invalid-type:Forge Admin 部署前改写节点属性
spring boot·低代码·工作流引擎
学长毕设2 天前
基于SpringBoot社区快递驿站物流配送系统-附源码
java·spring boot·后端
雾隐隐o2 天前
优搭校园 01|项目概览、技术选型与初始化
spring boot·mysql·vue
雪芽蓝域zzs2 天前
第 10 章:Maven 打包
spring boot
RuoyiOffice2 天前
SpringBoot3+Vue3 采购到付款:ERP、WMS与财务如何按同一来源协同
java·spring boot·架构·vue
企业数字化笔记2 天前
报表上线怎么对账?口径回归、权限抽检与差异定位
java·spring boot·mysql