主题
鉴权与权限点
一句话:接口上的
@PreAuthorize("@ss.hasPermission('system:user:create')")交给SecurityFrameworkService,它通过PermissionCommonApi问业务模块「这个用户有没有这个权限点」;业务模块把「角色 → 菜单 → 权限点」三段关系缓存进 Redis,超管在最后兜底短路。
适用场景:给新接口加权限、排查「按钮看得见但接口 403」、理解菜单/角色改动后为什么要清缓存。
不适用场景:行级数据过滤(看数据权限);登录态怎么解析(看 TokenAuthenticationFilter,本篇只在排错处提到)。
1. 调用链:从注解到缓存
java
@PreAuthorize("@ss.hasPermission('system:user:create')")
└─ @ss → SecurityFrameworkService(Bean 名固定为 ss)
└─ SecurityFrameworkServiceImpl#hasPermission → hasAnyPermissions
└─ PermissionCommonApi#hasAnyPermissions(pmforge-common 的跨模块契约)
└─ PermissionApiImpl(module-system 实现)
└─ PermissionServiceImpl#hasAnyPermissions
├─ getEnableUserRoleListByUserIdFromCache(userId) [缓存]
├─ hasAnyPermission(roles, permission)
│ ├─ menuService.getMenuIdListByPermissionFromCache(permission) [缓存]
│ └─ getMenuRoleIdListByMenuIdFromCache(menuId) [缓存]
└─ roleService.hasAnySuperAdmin(roleIds) [兜底]几个刻意的设计:
| 设计 | 位置 | 原因 |
|---|---|---|
Bean 名固定 ss | PmforgeSecurityAutoConfiguration#L76-L79 | 让 @PreAuthorize 里能写 @ss,不用记长类名 |
安全模块只声明 PermissionCommonApi | pmforge-common/.../business/system/permission/PermissionCommonApi.java#L10-L37 | starter 不反向依赖 module-system,业务模块提供实现 |
| 权限判断返回 boolean,不抛异常 | SecurityFrameworkServiceImpl#L30-L42 | 由 Spring Security 统一决定抛 AccessDeniedException,再交给 AccessDeniedHandler |
@EnableMethodSecurity(securedEnabled = true) | PmforgeWebSecurityConfigurerAdapter#L48 | 没有它,@PreAuthorize 根本不生效 |
2. PermissionServiceImpl 的三段判断
hasAnyPermissions(#L63-L84):
- 入参为空 →
true(没要求权限就是放行,#L65-L67)。 getEnableUserRoleListByUserIdFromCache(userId)拿角色;角色为空 →false(#L70-L73)。注意方法名里的 Enable:查到的角色会再按状态过滤,禁用角色不参与判断(#L259-L266)。- 逐个权限点调
hasAnyPermission,任一命中即true(#L76-L80)。 - 都没命中时,最后看
roleService.hasAnySuperAdmin(roleIds)(#L82-L83)——超管短路放在最后,所以正常角色的显式授权优先,超管只是兜底。
hasAnyPermission(#L93-L111):
- 先用权限点字符串换菜单 ID 列表:
menuService.getMenuIdListByPermissionFromCache(permission)(#L94)。 - 严格模式:权限点找不到任何菜单 → 直接
false(#L96-L98)。也就是说,代码里写了system:user:create,但数据库菜单表里没有这个permission,接口永远 403。 - 用用户角色 ID 与「该菜单关联的角色 ID」求交集(
#L101-L109)。
三段关系表(都在 Redis,key 定义见 module-system/.../dal/redis/RedisKeyConstants.java):
| 缓存 | key 常量 | 行 | 内容 | 失效时机 |
|---|---|---|---|---|
| 用户 → 角色 | USER_ROLE_ID_LIST | #L34 | userId -> Set<roleId> | 给用户分配角色(PermissionServiceImpl#L207)、删除用户(#L230-L234) |
| 菜单 → 角色 | MENU_ROLE_ID_LIST | #L42 | menuId -> Set<roleId> | 给角色分配菜单(#L135-L160)、删除角色(#L162-L175)、删除菜单(#L177-L181) |
| 权限点 → 菜单 | PERMISSION_MENU_ID_LIST | #L50 | permission -> List<menuId> | 菜单新增/修改/删除(MenuServiceImpl#L51-L52、#L69-L70、#L90-L91) |
assignRoleMenu 同时清两张表(@Caching(evict = ...),#L134-L140)且带 @DSTransactional,因为「改角色菜单」与「改菜单角色」是双向关系,只清一张会出现「新权限生效、旧权限还在」。
3. 超管短路与跨租户短路
- 超管:
RoleCodeEnum里super_admin是内置编码(enums/permission/RoleCodeEnum.java#L14-L16),hasAnySuperAdmin遍历角色code,命中即true(RoleServiceImpl#L234-L243)。因此超管不需要在菜单里逐项授权。 - 跨租户访问:
SecurityFrameworkUtils#skipPermissionCheck在「登录租户 ≠ 当前访问租户」时返回true(#L148-L158),hasAnyPermissions/hasAnyRoles/hasAnyScopes都会直接放行(#L32-L34、#L50-L62、#L70-L82)。这是为了让平台管理员切换到租户后不被目标租户的权限卡住,权限由租户切换接口本身控制(见TenantVisitContextInterceptor)。
4. 权限点命名规范
现状是字符串字面量,没有常量类(UserController 里直接写 'system:user:create')。命名沿用三段式:
text
<模块>:<资源>:<动作> 例:system:user:create、infra:codegen:preview| 段 | 取值来源 | 例子 |
|---|---|---|
| 模块 | 业务模块名,与路由前缀一致 | system、infra、bpm、crm |
| 资源 | 表/聚合名,小写 | user、role、job、codegen |
| 动作 | 平台惯用动词 | create、update、delete、query、export、preview、download、trigger、sync |
动作别自造同义词:查询用 query(列表/详情/分页共用),导出用 export,执行一次用 trigger,同步用 sync。同一接口的「新增/修改」如果前端共用一个按钮,后端仍然分别给 create、update,不要合并。
5. 新增一个权限点:三步
- 菜单按钮:在管理后台「菜单管理」新增类型为「按钮」的记录,
permission填三段式字符串(MenuTypeEnum.BUTTON(3),enums/permission/MenuTypeEnum.java#L17;MenuDO.permission字段在#L49)。保存后MenuServiceImpl会清PERMISSION_MENU_ID_LIST缓存(#L35-L52)。 - 接口注解:在 Controller 方法上加
@PreAuthorize("@ss.hasPermission('xxx:yyy:zzz')"),字符串必须与菜单里的permission逐字符一致(大小写、冒号、复数都不要发挥)。 - 前端指令:按钮显隐用前端自定义指令(PRD 里叫
v-hasPermission,见 01-03-角色权限 第 3.2.3 节),入参就是同一个权限点字符串;无权限时按钮不渲染,而不是禁用。
顺序很重要:先建菜单并给角色授权,再加 @PreAuthorize。反过来上线,接口会先 403(严格模式找不到菜单),而后端看起来「代码没问题」。
6. 401 与 403 怎么区分
| 状态码 | 触发点 | 常见原因 | 先看 |
|---|---|---|---|
401(CommonResult.code=401,HTTP 仍 200) | AuthenticationEntryPointImpl#L29-L33 | 没带 token、token 过期、token 解析后没有 LoginUser | TokenAuthenticationFilter#L42-L69 是否解析成功;SecurityProperties 的 header 名 |
403(CommonResult.code=403) | AccessDeniedHandlerImpl#L34-L41 | ① 接口权限点不满足;② 租户不匹配;③ 用户类型不对 | ① 看 PermissionServiceImpl#L63-L111;② 看 TenantSecurityWebFilter;③ 看 TokenAuthenticationFilter#L80-L83 |
两者都只写 CommonResult,不设置 HTTP 状态码(没有 @ResponseStatus),所以浏览器 Network 面板里可能都显示 200,要看响应体的 code。这是平台的统一约定,详见Web过滤器与统一响应。
7. 排错清单
| 症状 | 先看 | 判断依据 |
|---|---|---|
| 接口 401,日志无权限相关 | AuthenticationEntryPointImpl、TokenAuthenticationFilter#L44-L59 | token 没解析出 LoginUser,或 Authorization 前缀不是 Bearer |
| 接口 403,但角色确实有菜单 | PermissionServiceImpl#L93-L101 | 权限点字符串与菜单 permission 不完全一致;或菜单被删、缓存未清 |
| 改了角色菜单,权限没变 | PermissionServiceImpl#L135-L160 | MENU_ROLE_ID_LIST、PERMISSION_MENU_ID_LIST 是否清;是否走了 assignRoleMenu 之外的直改库 |
| 禁用角色仍然能访问 | PermissionServiceImpl#L259-L266 | 缓存里是旧角色;禁用角色后要清 USER_ROLE_ID_LIST |
| 超管也被 403 | RoleServiceImpl#L234-L243 | 角色 code 不是 super_admin;或用户类型不是后台用户 |
| 前端按钮不显示,接口能调 | 菜单表 permission 与前端指令入参 | 后端只认注解,前端只认菜单下发;两处必须同一个字符串 |
| 换租户后权限「全开」 | SecurityFrameworkUtils#L148-L158 | 跨租户访问会跳过权限检查,这是设计而非漏洞 |
@PreAuthorize 完全不生效 | PmforgeWebSecurityConfigurerAdapter#L48 | @EnableMethodSecurity 被移除,或 Controller 不在 base-package 扫描范围 |