一、背景:不是功能坏了,是边界破了
维护的是一套多门店 SaaS 后端:Java 17 + Spring Boot 3.5 + MyBatis-Plus,基于 RuoYi-Vue-Plus 的多租户架构,共享库、共享表,靠 tenant_id 做行级隔离。上线大半年一直正常,直到某天运营反馈:A 门店的店员在「订单导出」里看到了不属于自己门店的订单号。
这类问题最麻烦的地方在于,功能没坏、接口没报错、没有慢查询告警,只是数据边界悄悄破了。而且它不会稳定复现------列表页一切正常,只有导出偶尔出问题,很容易被当成「缓存没刷」糊弄过去。这篇把排查路径、修复代码、以及那些「没有 HTTP 请求」的旁路场景完整复盘一遍。
二、定位:从一条少了条件的 SQL 开始
排查只用了三步:
- 排除前端:抓请求,门店筛选参数正常,分页参数正常。
- 看真实 SQL :临时打开 SQL 日志(
mybatis-plus.configuration.log-impl: org.apache.ibatis.logging.stdout.StdOutImpl,生产建议用 p6spy),分别复现「订单列表」和「订单导出」。列表那条打印出来带AND tenant_id = 1001;导出那条完全没有tenant_id条件。 - 找差异 :列表走同步请求线程,导出走
@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」,也可投「数据库 / 数据安全」。文章类型选「原创」,不勾选任何推广或转载选项。