Skip to content

数据权限 ​

一句话:@DataPermission 只做一件事——在调用栈上压一个「开关对象」;真正拼 SQL 的是 MyBatis 插件 DataPermissionInterceptor,它按 Mapper 方法找到规则,把 dept_id IN (...) OR user_id = ? 塞进 WHERE。

适用场景:同一张表,不同角色看到不同行(部门经理看本部门、销售只看自己);给 Mapper 或 Service 方法加/去掉行级过滤。

不适用场景:租户之间的隔离(看多租户);接口级「能不能调」(看鉴权与权限点);表里没有 dept_id/user_id 这类归属列(先加列再谈规则)。

1. 完整链路 ​

java
@PreAuthorize / 业务方法
  └─ @DataPermission(AnnotationMatchingPointcut 类或方法)
       └─ DataPermissionAnnotationInterceptor  —— 入栈
            └─ Mapper 调用
                 └─ DataPermissionInterceptor(MyBatis-Plus InnerInterceptor)
                      └─ DataPermissionRuleHandler#getSqlSegment
                           └─ DataPermissionRuleFactoryImpl#getDataPermissionRule
                                └─ DeptDataPermissionRule#getExpression
                                     └─ 拼 AND 到 SQL 的 WHERE
            └─ DataPermissionAnnotationInterceptor  —— 出栈
阶段关键类行为
声明core/annotation/DataPermission.javaenable(#L23)、includeRules(#L28,优先于 exclude)、excludeRules(#L33)
切面DataPermissionAnnotationAdvisor类/方法两个 AnnotationMatchingPointcut 取并集(#L30-L34)
入栈/出栈DataPermissionAnnotationInterceptor#L33-L48方法执行前 add,finally 里 remove;支持嵌套,取栈顶
注解查找同文件 #L50-L70先查方法缓存,再方法注解,再类注解;类注解用 DATA_PERMISSION_NULL(#L27)占位
上下文DataPermissionContextHolder#L19-L20ThreadLocal<LinkedList<DataPermission>>(TTL 实现),get() 用 peekLast(#L27-L29)
选规则DataPermissionRuleFactoryImpl#L34-L65无注解→全部规则;enable=false→空;easy-trans 翻译调用→空;includeRules→只留这些;excludeRules→去掉这些
拼 SQLDataPermissionRuleHandler#L30-L62skipPermissionCheck()→null;按 mappedStatementId 取规则;表名不匹配跳过;多条规则用 AndExpression 叠加

DataPermissionRule 只有两个方法:Set<String> getTableNames()(#L25)与 Expression getExpression(String tableName, Alias tableAlias)(#L34)——规则自带「哪张表、拼什么」,框架只负责调度与组合。

2. DeptDataPermissionRule:五种范围,四种 SQL ​

getExpression 的判定顺序(DeptDataPermissionRule.java#L91-L146):

顺序判定结果
1未登录(#L93-L96)返回 null,不拼
2用户类型不是后台管理员(#L98-L100)返回 null,不拼(APP 用户不走部门权限)
3deptDataPermission.getAll()(#L117-L119)返回 null,不拼
4部门为空且 self=false(#L122-L125)WHERE null = null,恒为空集
5部门条件 + 本人条件(#L128-L145)只有部门→dept_id IN (...);只有本人→user_id = ?;都有→(dept_id IN (...) OR user_id = ?)

DataScopeEnum(enums/permission/DataScopeEnum.java#L20-L26)的五种范围在这里落成 SQL:

数据范围枚举DeptDataPermissionRespDTO生成的 SQL 片段
全部数据ALL(1)all=true无(不拼)
指定部门DEPT_CUSTOM(2)deptIds=配置的部门 + 自己部门dept_id IN (...)
本部门DEPT_ONLY(3)deptIds=自己部门dept_id IN (...)
本部门及子部门DEPT_AND_CHILD(4)deptIds=getChildDeptIdListFromCache(自己部门)dept_id IN (...)
仅本人SELF(5)self=trueuser_id = ?

范围的计算发生在 PermissionServiceImpl#getDeptDataPermission(#L276-L330),那个方法自己标了 @DataPermission(enable = false)(#L276),否则「查部门列表」会被部门权限再过滤一次,递归且查不到。

「哪张表用哪个列」由 DeptDataPermissionRule 的 deptColumns/userColumns 决定(#L71-L83,默认列名 dept_id/user_id,见 #L59-L60),注册在业务模块的配置里:pmforge-module-system/.../framework/datapermission/config/DataPermissionConfiguration.java#L17-L26 给 AdminUserDO 加 dept_id 与 user_id,给 DeptDO 加 id 作为部门列。

3. 与租户拦截器的顺序 ​

两个插件都被 MyBatisUtils.addInterceptor(interceptor, inner, 0) 插到索引 0(租户在 PmforgeTenantAutoConfiguration#L77-L85,数据权限在 PmforgeDataPermissionAutoConfiguration#L30-L39),而分页插件是在 PmforgeMybatisAutoConfiguration#L47-L54 构造 MybatisPlusInterceptor 时就 addInnerInterceptor 进去的。

由此得到两条结论:

  1. 分页一定在最后:后来者插到 0,分页留在数组末尾。分页必须在最后是 MyBatis-Plus 的硬要求,因为 count 语句要先看到完整的 WHERE。
  2. 租户与数据权限的相对顺序由装配顺序决定:两者插入点相同,谁后装配谁在前,两个自动配置类之间没有 @AutoConfigureBefore/After 约束。语义上无影响(都是 AND),但不要把「租户一定在前」当契约——新增插件时显式选择插入位置,别依赖这个偶然结果。

语义上两者都是往 WHERE 追加 AND,先后不影响结果;真正会出问题的是「谁排在分页后面」。

4. 如何新增一条规则 ​

场景 A:新表要按部门过滤。 不用写规则类,只要在业务模块的自定义器里登记列:

java
@Bean
public DeptDataPermissionRuleCustomizer sysDeptDataPermissionRuleCustomizer() {
    return rule -> {
        rule.addDeptColumn(ProjectDO.class);        // 用 dept_id 列
        rule.addUserColumn(ProjectDO.class, "owner_id"); // 或指定列名
    };
}

addDeptColumn/addUserColumn 有 Class 与「表名 + 列名」两组重载(#L179-L205),Class 版本经 TableInfoHelper 取表名。

场景 B:全新的规则(比如「项目成员才能看」)。 三步:

  1. 实现 DataPermissionRule:getTableNames() 返回涉及的表;getExpression(tableName, tableAlias) 用 JSqlParser 的 Expression 拼条件,列名走 MyBatisUtils.buildColumn(tableName, tableAlias, column) 以兼容别名。
  2. 注册成 Bean:DataPermissionRuleFactoryImpl 构造注入 List<DataPermissionRule>,所有规则 Bean 自动进入候选(#L24-L27)。
  3. 控制生效范围:默认「无注解 = 全部规则」,所以新规则会立刻作用于所有查询;用 @DataPermission(includeRules = XxxRule.class) 只让某方法用它,或用 excludeRules 排除(#L54-L62,include 优先)。

5. 排错:SQL 没拼上 / 拼多了 ​

没拼上,按这个顺序查:

  1. 方法(或类)有没有 @DataPermission?没有注解时框架默认「全部规则」,但 enable=false 会直接返回空。
  2. 目标表在不在规则的 getTableNames() 里?表名匹配用的是 MyBatisUtils.getTableName(DataPermissionRuleHandler#L47),别名、反引号都会被规范化,但表名写错不会报错,只会静默跳过。
  3. 当前用户是不是后台管理员类型?DeptDataPermissionRule#L98-L100 对非 ADMIN 用户直接返回 null。
  4. 是不是 easy-trans 的翻译调用?isTranslateCall 在栈里找到 SimpleTransService 时强制忽略(DataPermissionRuleFactoryImpl#L49-L51、#L74-L82),避免翻译字段被裁掉。
  5. 是不是跨租户访问?skipPermissionCheck() 为 true 时 DataPermissionRuleHandler#L33 直接返回 null。
  6. getDeptDataPermission 返回 all=true,或部门为空且 self=false(WHERE null = null,结果是空集而非「不过滤」)。

拼多了:

  • 类上标了 @DataPermission,导致该类所有方法都生效;改用方法级注解。
  • includeRules 没写或写成父类,导致默认规则全量叠加。
  • 多条规则同时命中同一张表时用 AndExpression 串联(DataPermissionRuleHandler#L58-L59),条件只会更多,不会互相覆盖。
  • 临时忽略用 DataPermissionUtils.executeIgnore(...)(DataPermissionUtils#L34-L59),或直接标 @DataPermission(enable = false);BPM 里有大量现成例子(如 BpmTaskCandidateInvoker#L91 的「避免找不到候选人」)。

6. 排错清单 ​

症状先看判断依据
SQL 里完全没有 dept_id 条件DataPermissionRuleFactoryImpl#L40-L62没注解时默认全部规则;enable=false、include/exclude 过滤、easy-trans 都会返回空
只有部分表被过滤DataPermissionRule#getTableNames + DataPermissionConfiguration规则的 deptColumns/userColumns 没登记这张表
条件拼成 WHERE null = nullDeptDataPermissionRule#L122-L125、#L130-L137无部门且不看自己;或规则拿不到列配置
条件多了一层DataPermissionRuleHandler#L45-L60多个规则命中同表,AND 叠加
查询部门列表时越查越少PermissionServiceImpl#L276缺 @DataPermission(enable = false),规则对自身查询生效
翻译字段为 nullDataPermissionRuleFactoryImpl#L74-L82翻译调用本应被忽略,检查栈里是否还有别的规则直接读上下文
换租户访问后数据不对DataPermissionRuleHandler#L33跨租户访问会跳过数据权限,但租户条件仍生效