Skip to content

鉴权与权限点 ​

一句话:接口上的 @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 名固定 ssPmforgeSecurityAutoConfiguration#L76-L79让 @PreAuthorize 里能写 @ss,不用记长类名
安全模块只声明 PermissionCommonApipmforge-common/.../business/system/permission/PermissionCommonApi.java#L10-L37starter 不反向依赖 module-system,业务模块提供实现
权限判断返回 boolean,不抛异常SecurityFrameworkServiceImpl#L30-L42由 Spring Security 统一决定抛 AccessDeniedException,再交给 AccessDeniedHandler
@EnableMethodSecurity(securedEnabled = true)PmforgeWebSecurityConfigurerAdapter#L48没有它,@PreAuthorize 根本不生效

2. PermissionServiceImpl 的三段判断 ​

hasAnyPermissions(#L63-L84):

  1. 入参为空 → true(没要求权限就是放行,#L65-L67)。
  2. getEnableUserRoleListByUserIdFromCache(userId) 拿角色;角色为空 → false(#L70-L73)。注意方法名里的 Enable:查到的角色会再按状态过滤,禁用角色不参与判断(#L259-L266)。
  3. 逐个权限点调 hasAnyPermission,任一命中即 true(#L76-L80)。
  4. 都没命中时,最后看 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#L34userId -> Set<roleId>给用户分配角色(PermissionServiceImpl#L207)、删除用户(#L230-L234)
菜单 → 角色MENU_ROLE_ID_LIST#L42menuId -> Set<roleId>给角色分配菜单(#L135-L160)、删除角色(#L162-L175)、删除菜单(#L177-L181)
权限点 → 菜单PERMISSION_MENU_ID_LIST#L50permission -> 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. 新增一个权限点:三步 ​

  1. 菜单按钮:在管理后台「菜单管理」新增类型为「按钮」的记录,permission 填三段式字符串(MenuTypeEnum.BUTTON(3),enums/permission/MenuTypeEnum.java#L17;MenuDO.permission 字段在 #L49)。保存后 MenuServiceImpl 会清 PERMISSION_MENU_ID_LIST 缓存(#L35-L52)。
  2. 接口注解:在 Controller 方法上加 @PreAuthorize("@ss.hasPermission('xxx:yyy:zzz')"),字符串必须与菜单里的 permission 逐字符一致(大小写、冒号、复数都不要发挥)。
  3. 前端指令:按钮显隐用前端自定义指令(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 解析后没有 LoginUserTokenAuthenticationFilter#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-L59token 没解析出 LoginUser,或 Authorization 前缀不是 Bearer
接口 403,但角色确实有菜单PermissionServiceImpl#L93-L101权限点字符串与菜单 permission 不完全一致;或菜单被删、缓存未清
改了角色菜单,权限没变PermissionServiceImpl#L135-L160MENU_ROLE_ID_LIST、PERMISSION_MENU_ID_LIST 是否清;是否走了 assignRoleMenu 之外的直改库
禁用角色仍然能访问PermissionServiceImpl#L259-L266缓存里是旧角色;禁用角色后要清 USER_ROLE_ID_LIST
超管也被 403RoleServiceImpl#L234-L243角色 code 不是 super_admin;或用户类型不是后台用户
前端按钮不显示,接口能调菜单表 permission 与前端指令入参后端只认注解,前端只认菜单下发;两处必须同一个字符串
换租户后权限「全开」SecurityFrameworkUtils#L148-L158跨租户访问会跳过权限检查,这是设计而非漏洞
@PreAuthorize 完全不生效PmforgeWebSecurityConfigurerAdapter#L48@EnableMethodSecurity 被移除,或 Controller 不在 base-package 扫描范围