在企业级应用中，多租户架构（Multi-Tenancy）是一个非常常见的需求。比如 SaaS 平台中，每个客户（租户）的数据需要隔离存储，通常通过在每张业务表中增加一个tenant_id字段来实现。
MyBatis-Plus 提供了强大的多租户插件（TenantLineInnerInterceptor），可以自动在 SQL 中注入租户条件。但在某些特殊场景下，我们可能希望临时忽略租户过滤，比如：
- 管理员查看所有租户数据
- 数据迁移、批量处理任务
- 异步任务中绕过多租户限制
这时候问题来了：如何做到“一次设置，全程忽略租户”？即使在异步线程、嵌套方法调用中也能生效？
今天我们就来手把手教你实现这个高级功能！
一、需求场景说明
假设你正在开发一个 SaaS 后台管理系统，普通用户只能看到自己租户的数据，但超级管理员可以查看全部租户的数据。
✅ 正确做法：在请求入口处判断是否为超级管理员，如果是，则在整个请求链路（包括异步任务、Service 嵌套调用）中都忽略租户过滤。
❌ 反例做法：每次调用 Mapper 时手动传参或写特殊 SQL，代码冗余且容易出错。
二、技术选型与原理
- Spring Boot 3.x
- MyBatis-Plus 3.5+
- ThreadLocal + InheritableThreadLocal：用于在线程上下文中传递“忽略租户”标志
- 自定义 MyBatis-Plus 租户处理器：动态决定是否应用租户过滤
💡 核心思想：
使用InheritableThreadLocal存储“是否忽略租户”的开关。
因为普通ThreadLocal在异步线程（如@Async）中无法继承父线程的值，而InheritableThreadLocal可以。
三、代码实现
1. 自定义忽略租户上下文工具类
// TenantIgnoreContext.java public class TenantIgnoreContext { // 使用 InheritableThreadLocal 支持子线程继承 private static final InheritableThreadLocal<Boolean> IGNORE_TENANT = new InheritableThreadLocal<>(); public static void setIgnore(boolean ignore) { IGNORE_TENANT.set(ignore); } public static boolean isIgnore() { Boolean ignore = IGNORE_TENANT.get(); return ignore != null && ignore; } public static void clear() { IGNORE_TENANT.remove(); } }⚠️ 注意：必须在请求结束时调用
clear()，否则可能造成内存泄漏或污染下一个请求！
2. 自定义租户处理器（关键！）
// CustomTenantHandler.java import com.baomidou.mybatisplus.extension.plugins.handler.TenantLineHandler; import net.sf.jsqlparser.expression.Expression; import net.sf.jsqlparser.expression.LongValue; public class CustomTenantHandler implements TenantLineHandler { @Override public Expression getTenantId() { // 正常返回租户ID，比如从登录信息中获取 // 这里简化为固定值，实际项目应从 SecurityContext 或 ThreadLocal 获取 return new LongValue(1L); } @Override public String getTenantIdColumn() { return "tenant_id"; } @Override public boolean ignoreTable(String tableName) { // 某些表不需要租户隔离，比如字典表、系统配置表 return false; } // 重写此方法！决定是否应用租户过滤 @Override public boolean ignoreInsert(List<Column> columns, String tenantIdColumn) { return TenantIgnoreContext.isIgnore(); } // 关键：全局控制是否忽略租户 @Override public boolean ignoreTableWhenInsertOrUpdateOrDelete(String tableName) { return TenantIgnoreContext.isIgnore(); } // MyBatis-Plus 3.5+ 推荐重写此方法 @Override public boolean ignoreTableForSelect(String tableName) { return TenantIgnoreContext.isIgnore(); } }🔥 重点：所有
ignoreXXX方法都返回TenantIgnoreContext.isIgnore()，实现统一控制。
3. 配置 MyBatis-Plus 多租户插件
// MybatisPlusConfig.java @Configuration @MapperScan("com.example.demo.mapper") public class MybatisPlusConfig { @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); // 多租户插件 TenantLineInnerInterceptor tenantInterceptor = new TenantLineInnerInterceptor(); tenantInterceptor.setTenantLineHandler(new CustomTenantHandler()); interceptor.addInnerInterceptor(tenantInterceptor); // 分页插件等其他拦截器... interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }4. 在 Controller 中使用（支持同步/异步）
@RestController public class UserController { @Autowired private UserService userService; @Autowired private AsyncTask asyncTask; @GetMapping("/users") public List<User> getAllUsers(@RequestParam(required = false) Boolean admin) { try { // 如果是管理员，开启忽略租户模式 if (Boolean.TRUE.equals(admin)) { TenantIgnoreContext.setIgnore(true); } // 同步调用 List<User> users = userService.listAll(); // 异步调用（子线程会继承 ignore 标志！） asyncTask.logUserCount(); return users; } finally { // 必须清理！防止 ThreadLocal 泄漏 TenantIgnoreContext.clear(); } } }// UserService.java @Service public class UserService { @Autowired private UserMapper userMapper; public List<User> listAll() { // 即使嵌套调用，也能正确识别是否忽略租户 return userMapper.selectList(null); } }// AsyncTask.java @Component public class AsyncTask { @Autowired private UserMapper userMapper; @Async public void logUserCount() { // 异步线程中依然能拿到 ignore 标志！ long count = userMapper.selectCount(null); System.out.println("Total users (ignoring tenant): " + count); } }✅ 测试结果：
- 访问
/users?admin=true→ 查询所有租户数据- 访问
/users→ 仅查询当前租户数据- 异步任务中也生效！
四、反例 & 注意事项
❌ 反例1：只在 Service 层硬编码忽略
// 错误！每次都要改，无法复用 public List<User> getAllUsersForAdmin() { // 手动写 SQL 或关闭插件？不可维护！ }❌ 反例2：忘记清理 ThreadLocal
// 危险！可能导致下一个请求错误地继承了 ignore 标志 TenantIgnoreContext.setIgnore(true); // ... 忘记 clear()⚠️ 注意事项：
- 必须使用
InheritableThreadLocal，否则@Async、线程池中的任务无法继承上下文。 - 务必在 finally 块中调用
clear()，建议封装成 AOP 切面自动清理。 - 不要在过滤器/拦截器之外的地方随意设置，避免逻辑混乱。
- 测试时要覆盖同步、异步、异常路径，确保上下文正确传播和清理。
五、进阶建议：用 AOP 自动管理上下文
你可以写一个注解@IgnoreTenant，配合 AOP 自动设置和清理：
@Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface IgnoreTenant {}@Aspect @Component public class TenantIgnoreAspect { @Around("@annotation(IgnoreTenant)") public Object ignoreTenant(ProceedingJoinPoint joinPoint) throws Throwable { try { TenantIgnoreContext.setIgnore(true); return joinPoint.proceed(); } finally { TenantIgnoreContext.clear(); } } }然后在方法上直接使用：
@IgnoreTenant @GetMapping("/admin/users") public List<User> adminGetAllUsers() { return userService.listAll(); // 自动忽略租户 }总结
通过InheritableThreadLocal + 自定义 TenantHandler，我们实现了：
✅ 一次设置，全程生效
✅ 支持同步、异步、嵌套调用
✅ 代码清晰，无侵入性
✅ 安全可控，避免内存泄漏
这才是多租户系统中“临时绕过租户隔离”的优雅解法！
视频看了几百小时还迷糊？关注我，几分钟让你秒懂！
