架构与系统设计 / 系统课时

租户拦截器原理

租户拦截器原理

租户拦截器的目标是在业务代码无感知的情况下,为 SQL 自动补上租户条件。本课从一条查询的执行链路出发,说明解析、条件注入、表过滤和参数绑定分别发生在哪里,以及哪些边界仍需业务层主动防守。

学习目标

  • 说清租户拦截器改写 SQL 的完整执行顺序
  • 理解查询、更新、删除和新增语句的注入差异
  • 区分 MyBatis 参数绑定与租户表达式注入的安全边界

一条查询如何被改写

Mapper 方法执行后,MyBatis 会先生成待执行 SQL 和参数映射。租户拦截器在 JDBC 真正创建语句之前取得 SQL,将文本解析成抽象语法树,再定位主表、别名、连接条件和原有 WHERE,最后把租户条件合并回 SQL。

租户 SQL 拦截器执行链路

解析器处理的是 SQL 结构,而不是简单字符串拼接。因此它能在已有条件外加括号、识别表别名,并尽量避免把条件插入子句的错误位置。解析失败时不应静默放行,否则一次不兼容 SQL 就可能绕过隔离。

SQL 解析与条件注入

下面是片段示例。原查询按状态筛选订单,其中 ? 对应 Mapper 传入的业务参数。

sql
SELECT id, amount, status
FROM pay_order
WHERE status = ?
ORDER BY id DESC;

租户上下文为 1001 时,预期改写结果如下:

sql
SELECT id, amount, status
FROM pay_order
WHERE tenant_id = 1001
  AND status = ?
ORDER BY id DESC;

原有 WHERE 不会被覆盖,而是与租户条件组合。若主表使用别名,例如 pay_order o,条件应写成 o.tenant_id = 1001,避免多表查询出现列名歧义。带有子查询、联合查询或复杂连接的 SQL,需要通过集成测试确认解析器对每个作用域的处理符合预期。

不同语句的隔离行为

查询、更新和删除通常都在目标表条件中追加 tenant_id,确保只能读取或修改当前租户的数据。新增语句则需要把租户字段和值加入列清单;若业务 SQL 已显式提供租户字段,插件应避免重复插入。

平台级表不属于任何租户,例如租户主表、行政区划表或数据库迁移记录表。这类表应进入明确的忽略清单。忽略规则必须以表名白名单实现,不能因为“没有租户上下文”就跳过全部隔离。

对于连接查询,还要区分租户表与公共表。租户表必须注入条件,公共表可以忽略;如果一条 SQL 同时连接多个租户表,应确认每个租户表都受到约束,而不是只限制主表。

参数绑定与安全边界

MyBatis 会继续按照原有参数映射绑定 status 等业务参数。租户插件常通过 JSQLParser 的 Expression 返回租户值;若使用 LongValue,租户编号会直接成为改写后 SQL 的数字字面量,而不是自动新增一个 JDBC ? 参数。

因此,租户编号必须来自经过认证和校验的上下文,只允许转换为受控的数值或安全表达式,不能把请求头原文直接拼入 SQL。上下文缺失时应立即失败,采用“拒绝执行”而不是“默认查询全部数据”的策略。

拦截器只负责 SQL 层隔离,不能替代身份认证、数据权限和唯一约束。异步任务、消息消费和定时任务也必须显式建立租户上下文,并在执行结束后清理,避免线程复用造成串租户。

常见误区

  • 认为所有 SQL 都能自动解析:自定义函数、特殊方言和手写复杂 SQL 仍需测试
  • 把忽略表当成临时绕过开关:忽略范围过大会形成永久数据越权入口
  • 只验证查询语句:更新、删除、批量新增和子查询同样需要隔离测试

本课总结

  • 租户拦截器在 SQL 生成后、JDBC 执行前完成结构解析与条件注入
  • 表过滤决定哪些表参与隔离,缺失租户上下文时应直接拒绝执行
  • 原业务参数仍由 MyBatis 绑定,租户表达式必须来自可信且经过校验的上下文

下一课预告

下一课将把原理落到 MyBatis-Plus,完成 TenantLineInnerInterceptor、租户字段规则、公共表忽略清单和请求上下文的实际配置。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

租户拦截器原理

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通