这篇文章基于一个真实的物联网 SaaS 网站项目。记录了在 MyBatis-Plus + PageHelper 分页插件的基础组件程序下使用 AOP 切面 + 自定义注解 + ThreadLocal + SQL 拦截器实现动态数据权限过滤的完整方案，还有在分页场景下踩到的“查不到租户信息”的深坑与排查过程。

一、背景与需求

在多租户 SaaS 程序中，不同角色登录后看到的数据范围不同。例如的观点是，

• 租户管理员能看到本租户下所有设备
• 普通使用者只能看到其角色绑定的区域/机构下的设备

数据权限控制需要在业务代码无感知的情况下自动给 SQL 追加过滤条件。避免每个查询手动拼接，

技术栈

组件	版本	作用
MyBatis-Plus3.x ORM 框架，提供 InnerInterceptor 机制
PageHelper6..1分页插件，基于 ThreadLocal 实现自动分页
Spring AOP-切面拦截，在方法执行前后织入权限逻辑
JSqlParser-SQL 解析，动态 WHERE 条件

二、整体架构设计

数据权限过滤的主要思路是：AOP 切面负责收集权限上下文 → ThreadLocal 传递 → SQL 拦截器负责 SQL.

组件职责划分

<─────────────────────────────────────────────────────────────>
| 业务层 Service |
| PageHelper.startPage + mapper.getEquipmentList |
<──────────────────────────┬──────────────────────────────────>
| @DataScope 注解触发
▼
<─────────────────────────────────────────────────────────────>
| AOP 切面 DeviceDataScopeAspect |
| . 获取当前登录使用者 |
| . 查询租户信息。判断是否管理员 |
| . 非管理员：查询角色绑定的区域/机构权限 |
| . 将权限上下文写入 ThreadLocal |
| . point.proceed 执行目标方法 |
| . finally 清理 ThreadLocal |
<──────────────────────────┬──────────────────────────────────>
| MyBatis 执行 SQL
▼
<─────────────────────────────────────────────────────────────>
| SQL 拦截器 DeviceDataScopeInterceptor |
| . 从 ThreadLocal 读取权限上下文 |
| . 管理员：跳过 |
| . 非管理员：用 JSqlParser
SQL，追加 WHERE 条件 |
| 如：district_id IN |
<─────────────────────────────────────────────────────────────>

主要组件代码

标注在 Mapper 方法上，声明该查询需要数据权限过滤，并指定过滤字段：

@Target
@Retention
public @interface DataScope {
// 数据资源类型：设备/区域/机构/人员
DataResourceEnum dataResource default DataResourceEnum.DEVICE;其实，// 数据库表中的过滤字段别名。如 "e.district_id"
String filterFieldAlias default "device_id";// 是否走子查询模式
boolean subQuery default false;String subQueryField default "";String subQueryTable default "";
String subQueryFilterFieldAlias default "";}

再看使用示例，

@DataScope
List getEquipmentList EquipmentListQuery dto);

在 AOP 切面和 SQL 拦截器之间传递权限数据：

public class SqlEnhanceContext {
private static final ThreadLocal CONTEXT = new ThreadLocal<>;public static void set {
Map map = CONTEXT.get;if {
map = new HashMap<>;CONTEXT.set，其实，}
map.put;}
public static Object get {
Map map = CONTEXT.get;return map，= null?map.get : null;}
public static void clear { CONTEXT.remove;}
}

存储的上下文键值：

` Note: The assistant's answer has been truncated due to token limits.

Key	含义
: filtering field name e.g.,e.district_id.

---