架构与系统设计 / 系统课时
MyBatis-Plus 租户插件
MyBatis-Plus 租户插件
本课完成一套可落地的 MyBatis-Plus 行级租户隔离配置:引入插件、保存当前租户、定义 tenant_id 注入规则,并通过 SQL 日志验证查询是否自动带上租户条件。
学习目标
- 配置
TenantLineInnerInterceptor并接入 MyBatis-Plus 拦截器链 - 定义租户编号、租户字段和公共表忽略规则
- 正确设置、清理租户上下文并验证最终 SQL
前置约定
示例使用 Spring Boot 3、MyBatis-Plus 3.5.x 和数据库字段 tenant_id。租户业务表必须真实存在该字段并建立合适索引;平台公共表则通过白名单忽略。版本号应替换为项目统一管理的已验证版本。
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-spring-boot3-starter</artifactId>
<version>${mybatis-plus.version}</version>
</dependency>该配置片段生效后,Spring Boot 会加载 MyBatis-Plus 基础组件。验证方法是启动应用并确认依赖解析成功;若项目已通过父 POM 管理版本,可以删除显式 version,避免同一依赖出现多个版本。
保存当前租户上下文
租户编号应由认证结果或可信网关信息确定。下面的类使用 ThreadLocal 保存一次同步请求中的租户编号,并在缺失时直接抛错,防止查询退化为全量访问。
package com.example.multitenant.context;
public final class TenantContextHolder {
private static final ThreadLocal<Long> CURRENT_TENANT = new ThreadLocal<>();
private TenantContextHolder() {
}
public static void setTenantId(Long tenantId) {
if (tenantId == null || tenantId <= 0) {
throw new IllegalArgumentException("tenantId must be a positive number");
}
CURRENT_TENANT.set(tenantId);
}
public static long requireTenantId() {
Long tenantId = CURRENT_TENANT.get();
if (tenantId == null) {
throw new IllegalStateException("Tenant context is missing");
}
return tenantId;
}
public static void clear() {
CURRENT_TENANT.remove();
}
}该类不产生独立控制台输出。验证重点是:未设置租户时调用 requireTenantId() 必须失败;请求结束后调用 clear(),避免线程池复用时残留上一次请求的租户编号。
配置租户插件
下面配置把租户插件加入 MyBatis-Plus 拦截器链。getTenantId() 返回当前租户表达式,getTenantIdColumn() 指定统一字段名,ignoreTable() 只放行明确的公共表。
package com.example.multitenant.config;
import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
import com.baomidou.mybatisplus.extension.plugins.handler.TenantLineHandler;
import com.baomidou.mybatisplus.extension.plugins.inner.TenantLineInnerInterceptor;
import com.example.multitenant.context.TenantContextHolder;
import net.sf.jsqlparser.expression.Expression;
import net.sf.jsqlparser.expression.LongValue;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.Locale;
import java.util.Set;
@Configuration
public class MybatisPlusTenantConfig {
private static final Set<String> IGNORED_TABLES = Set.of(
"sys_tenant",
"flyway_schema_history"
);
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
TenantLineHandler tenantLineHandler = new TenantLineHandler() {
@Override
public Expression getTenantId() {
long tenantId = TenantContextHolder.requireTenantId();
return new LongValue(Long.toString(tenantId));
}
@Override
public String getTenantIdColumn() {
return "tenant_id";
}
@Override
public boolean ignoreTable(String tableName) {
return IGNORED_TABLES.contains(
tableName.toLowerCase(Locale.ROOT)
);
}
};
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
interceptor.addInnerInterceptor(
new TenantLineInnerInterceptor(tenantLineHandler)
);
return interceptor;
}
}该配置生效后,普通 Mapper 的查询、更新、删除和新增 SQL 会按插件规则处理。项目若还使用分页插件,应先加入租户插件,再加入分页插件,让分页统计基于已经隔离的数据集计算。
在请求入口设置并清理
以下过滤器使用 X-Tenant-Id 演示上下文生命周期。生产环境不应直接信任客户端请求头,而应从已校验的登录令牌、网关签名或服务端会话中取得租户编号。
package com.example.multitenant.web;
import com.example.multitenant.context.TenantContextHolder;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;
@Component
public class TenantContextFilter extends OncePerRequestFilter {
@Override
protected void doFilterInternal(
HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain
) throws ServletException, IOException {
String rawTenantId = request.getHeader("X-Tenant-Id");
if (rawTenantId == null || rawTenantId.isBlank()) {
response.sendError(400, "Missing tenant context");
return;
}
final long tenantId;
try {
tenantId = Long.parseLong(rawTenantId);
} catch (NumberFormatException ex) {
response.sendError(400, "Invalid tenant context");
return;
}
try {
TenantContextHolder.setTenantId(tenantId);
filterChain.doFilter(request, response);
} finally {
TenantContextHolder.clear();
}
}
}预期结果:请求缺少或携带非法租户编号时返回 HTTP 400;合法请求完成后,无论业务成功还是抛出异常,当前线程中的租户上下文都会被清理。
HTTP status: 400验证自动隔离
下面是片段示例,依赖项目中已经存在的 OrderMapper。执行 Mapper 前设置租户 1001,结束后必须清理上下文。
TenantContextHolder.setTenantId(1001L);
try {
orderMapper.selectList(null);
} finally {
TenantContextHolder.clear();
}开启 MyBatis SQL 日志后,预期结果应包含租户条件。实际字段清单、日志前缀和参数格式会因项目配置不同而变化。
Preparing: SELECT id, order_no, amount, tenant_id
FROM pay_order
WHERE tenant_id = 1001还应补充三类集成测试:租户 1001 看不到租户 1002 的数据;公共表查询不追加 tenant_id;缺失租户上下文时 Mapper 调用失败。不要只验证正常查询,还要覆盖更新、删除和批量新增。
本课总结
TenantLineInnerInterceptor负责改写 SQL,TenantLineHandler提供租户值、字段名和忽略表规则- 租户上下文必须在请求进入时设置,并在
finally中清理 - SQL 日志与跨租户集成测试是确认自动隔离真正生效的关键手段
下一课预告
下一课可以继续处理复杂 SQL 与插件边界,包括多表连接、子查询、批量操作、忽略策略和自定义 Mapper 的隔离验证。