主题
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 拦截器 + 注解 Advisor | datapermission/config/PmforgeDataPermissionAutoConfiguration.java |
PmforgeDeptDataPermissionAutoConfiguration | 装配 DeptDataPermissionRule 并应用所有 Customizer | datapermission/config/PmforgeDeptDataPermissionAutoConfiguration.java |
DataPermission | 注解:enable()、includeRules()、excludeRules() | core/annotation/DataPermission.java |
DataPermissionAnnotationAdvisor / …Interceptor | 方法/类上的注解拦截,入栈/出栈 | core/aop/ |
DataPermissionContextHolder | TransmittableThreadLocal<LinkedList<DataPermission>>,支持嵌套 | core/aop/DataPermissionContextHolder.java |
DataPermissionRuleHandler | MultiDataPermissionHandler:把各规则的 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.context | core/rule/dept/DeptDataPermissionRule.java |
DeptDataPermissionRuleCustomizer | 函数式接口:业务声明「哪些表用 dept_id、哪些用 user_id」 | core/rule/dept/DeptDataPermissionRuleCustomizer.java |
DataPermissionUtils | executeIgnore(...):临时加一个 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_NAME | dept_id | 默认部门列 |
DeptDataPermissionRule.USER_COLUMN_NAME | user_id | 默认用户列 |
DataPermissionContextHolder 的 CONTEXT_KEY | DeptDataPermissionRule 的类简名 | 部门权限结果在 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. 常见坑
- 只有
ADMIN用户才会被加部门条件:DeptDataPermissionRule.getExpression在userType != UserTypeEnum.ADMIN时直接返回null,即「其他用户类型看到全部数据」——新增用户类型时务必评估。 deptIds为空且self=false时生成WHERE null = null:这是刻意保证「查不到任何数据」的写法,看到 SQL 里出现null = null不要以为拼接出错。- 拿不到权限数据会抛
NullPointerException:PermissionCommonApi.getDeptDataPermission返回null时抛「LoginUser(%d) Table(%s/%s) 未返回数据权限」,属于 500 而非业务异常。 - easy-trans 翻译与跨租户访问会「静默跳过」:前者靠扫描线程栈里的
SimpleTransService(注释:「目前暂时只有这个办法」),后者靠SecurityFrameworkUtils.skipPermissionCheck();这两条都不会打日志,排查「为什么这次没过滤」时容易被忽略。 - 取不到条件时不再抛异常:
buildDeptExpression/buildUserExpression都为空时返回null = null并只log.warn(原实现是 throw,已被注释掉,TODO 保留)。 - 拦截器顺序不能乱:它和租户插件都用
addInterceptor(..., 0),后注册的会插到前面;自定义 MyBatis 拦截器时不要抢到它们之前。
7. 关联页面
- starter-mybatis:JSqlParser 与拦截器链
- starter-security:
skipPermissionCheck与LoginUser - starter-biz-tenant:两个插件都要排在第 0 位
- 横切机制、部门管理、权限与角色