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

MyBatis-Plus 租户插件

MyBatis-Plus 租户插件

本课完成一套可落地的 MyBatis-Plus 行级租户隔离配置:引入插件、保存当前租户、定义 tenant_id 注入规则,并通过 SQL 日志验证查询是否自动带上租户条件。

学习目标

  • 配置 TenantLineInnerInterceptor 并接入 MyBatis-Plus 拦截器链
  • 定义租户编号、租户字段和公共表忽略规则
  • 正确设置、清理租户上下文并验证最终 SQL

前置约定

示例使用 Spring Boot 3、MyBatis-Plus 3.5.x 和数据库字段 tenant_id。租户业务表必须真实存在该字段并建立合适索引;平台公共表则通过白名单忽略。版本号应替换为项目统一管理的已验证版本。

xml
<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 保存一次同步请求中的租户编号,并在缺失时直接抛错,防止查询退化为全量访问。

java
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() 只放行明确的公共表。

java
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 演示上下文生命周期。生产环境不应直接信任客户端请求头,而应从已校验的登录令牌、网关签名或服务端会话中取得租户编号。

java
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;合法请求完成后,无论业务成功还是抛出异常,当前线程中的租户上下文都会被清理。

text
HTTP status: 400

验证自动隔离

下面是片段示例,依赖项目中已经存在的 OrderMapper。执行 Mapper 前设置租户 1001,结束后必须清理上下文。

java
TenantContextHolder.setTenantId(1001L);
try {
    orderMapper.selectList(null);
} finally {
    TenantContextHolder.clear();
}

开启 MyBatis SQL 日志后,预期结果应包含租户条件。实际字段清单、日志前缀和参数格式会因项目配置不同而变化。

text
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 的隔离验证。

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

目录与阅读设置

阅读设置

17

记录一个想法

MyBatis-Plus 租户插件

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

登录哪都通