Skip to content

starter-biz-data-permission ​

1. 职责 ​

在 SQL 层做「部门级数据权限」:用 JSqlParser 解析出表名,按当前用户的部门数据权限(本部门 / 本部门及以下 / 仅本人 / 全部)给 SELECT 补 dept_id IN (...) OR user_id = ? 条件,业务代码完全无感。

它提供一套可扩展的规则模型:DataPermissionRule 定义「哪些表 + 什么条件」,@DataPermission 控制某方法开/关/只用哪几条规则,规则栈支持方法嵌套。

它不解决:功能权限(starter-security 的 @PreAuthorize)、行级之外的列脱敏(pmforge-common 的 @DesensitizeBy)、非 MyBatis 的 SQL(如手写 JDBC、报表引擎)。

本节路径均省略公共前缀 framework/pmforge-spring-boot-starter-biz-data-permission/src/main/java/com/pmforge/framework/。

2. 关键类 ​

类作用路径
PmforgeDataPermissionAutoConfiguration规则工厂 + MyBatis 拦截器 + 注解 Advisordatapermission/config/PmforgeDataPermissionAutoConfiguration.java
PmforgeDeptDataPermissionAutoConfiguration装配 DeptDataPermissionRule 并应用所有 Customizerdatapermission/config/PmforgeDeptDataPermissionAutoConfiguration.java
DataPermission注解:enable()、includeRules()、excludeRules()core/annotation/DataPermission.java
DataPermissionAnnotationAdvisor / …Interceptor方法/类上的注解拦截,入栈/出栈core/aop/
DataPermissionContextHolderTransmittableThreadLocal<LinkedList<DataPermission>>,支持嵌套core/aop/DataPermissionContextHolder.java
DataPermissionRuleHandlerMultiDataPermissionHandler:把各规则的 Expression 用 AND 拼到 SQL 上core/db/DataPermissionRuleHandler.java
DataPermissionRule接口:getTableNames() + getExpression(tableName, alias)core/rule/DataPermissionRule.java
DataPermissionRuleFactory / Impl按注解与调用栈决定本次要生效的规则列表core/rule/
DeptDataPermissionRule部门规则的实现:dept_id/user_id 两列,结果缓存在 LoginUser.contextcore/rule/dept/DeptDataPermissionRule.java
DeptDataPermissionRuleCustomizer函数式接口:业务声明「哪些表用 dept_id、哪些用 user_id」core/rule/dept/DeptDataPermissionRuleCustomizer.java
DataPermissionUtilsexecuteIgnore(...):临时加一个 enable=false 的注解对象core/util/DataPermissionUtils.java

3. 自动配置 ​

配置类生效条件注册了什么
PmforgeDataPermissionAutoConfiguration始终装配DataPermissionRuleFactory(收集所有 DataPermissionRule Bean);DataPermissionRuleHandler + DataPermissionInterceptor,用 MyBatisUtils.addInterceptor(interceptor, inner, 0) 放在第 0 位;DataPermissionAnnotationAdvisor
PmforgeDeptDataPermissionAutoConfiguration@ConditionalOnClass(LoginUser.class) + @ConditionalOnBean(DeptDataPermissionRuleCustomizer.class)DeptDataPermissionRule(注入 PermissionCommonApi),逐个执行 customizer.customize(rule)

规则生效判定(DataPermissionRuleFactoryImpl):没有规则 → 空;上下文栈为空 → 全部规则;enable=false → 空;调用栈里有 easy-trans 的 SimpleTransService → 空(翻译时不再过滤);includeRules 非空 → 只留这些;excludeRules 非空 → 排除;否则全部。

DeptDataPermissionRule 生成条件的逻辑:非 ADMIN 用户 → 不添加条件;getAll() → 不添加;deptIds 为空且 self=false → WHERE null = null(保证查不到数据);否则 dept_id IN (...) 与 user_id = ? 用 OR 组合。

4. 配置项 ​

前缀键默认值说明
—无—本模块没有 @ConfigurationProperties;规则靠 DeptDataPermissionRuleCustomizer 声明,不靠 yaml

规则内部常量(写死):

常量值含义
DeptDataPermissionRule.DEPT_COLUMN_NAMEdept_id默认部门列
DeptDataPermissionRule.USER_COLUMN_NAMEuser_id默认用户列
DataPermissionContextHolder 的 CONTEXT_KEYDeptDataPermissionRule 的类简名部门权限结果在 LoginUser.context 里的缓存键

5. 扩展点 ​

  • 声明哪些表受部门规则管:在业务模块写 @Bean DeptDataPermissionRuleCustomizer,调 rule.addDeptColumn(UserDO.class) / rule.addUserColumn(OrderDO.class, "creator_id")。没有 Customizer,部门规则根本不会装配。
  • 加自定义规则:实现 DataPermissionRule 并注册 Bean,框架自动收集;想只对某方法生效就用 @DataPermission(includeRules = MyRule.class)。
  • 临时关闭:DataPermissionUtils.executeIgnore(() -> service.list()),或用 @DataPermission(enable = false)。
  • 排除某条规则:@DataPermission(excludeRules = XxxRule.class)。
  • 缓存权限:规则结果会写进 LoginUser.context,同一请求内多次查询不会重复调 PermissionCommonApi。

6. 常见坑 ​

  1. 只有 ADMIN 用户才会被加部门条件:DeptDataPermissionRule.getExpression 在 userType != UserTypeEnum.ADMIN 时直接返回 null,即「其他用户类型看到全部数据」——新增用户类型时务必评估。
  2. deptIds 为空且 self=false 时生成 WHERE null = null:这是刻意保证「查不到任何数据」的写法,看到 SQL 里出现 null = null 不要以为拼接出错。
  3. 拿不到权限数据会抛 NullPointerException:PermissionCommonApi.getDeptDataPermission 返回 null 时抛「LoginUser(%d) Table(%s/%s) 未返回数据权限」,属于 500 而非业务异常。
  4. easy-trans 翻译与跨租户访问会「静默跳过」:前者靠扫描线程栈里的 SimpleTransService(注释:「目前暂时只有这个办法」),后者靠 SecurityFrameworkUtils.skipPermissionCheck();这两条都不会打日志,排查「为什么这次没过滤」时容易被忽略。
  5. 取不到条件时不再抛异常:buildDeptExpression/buildUserExpression 都为空时返回 null = null 并只 log.warn(原实现是 throw,已被注释掉,TODO 保留)。
  6. 拦截器顺序不能乱:它和租户插件都用 addInterceptor(..., 0),后注册的会插到前面;自定义 MyBatis 拦截器时不要抢到它们之前。

7. 关联页面 ​