权限控制
讲解前端按钮级权限的 usePermission hook 用法与路由级访问控制,及判定规则。
给按钮、入口加权限裁剪,或排查「按钮为什么不出现」时,读这页。页面级权限由菜单下发与路由守卫控制(没权限的菜单根本不下发,见路由与页签),本页讲页面内部的按钮级权限与判定规则。
权限码与判定规则
权限码是三段式字符串,与后端 CRUD 控制器自动生成的权限标识一一对应,例如 system:user:create、system:role:delete。判定逻辑在 src/lib/permission.ts,两条约定:
- 权限集合含
*:*:*时任何校验直接通过(超级管理员); - 校验目标不传权限码(
undefined)时视为无需权限,直接通过。
权限数据来自 GET /auth/user/info,登录后写入 zustand 认证 store(src/stores/auth/auth-store.ts)。恢复会话(浏览器刷新)时权限先为空数组,用户信息请求落定后才填充;(main)/(app) 布局路由会等这步完成才渲染页面,页面组件里读到的权限始终是完整的。
usePermission hook
按钮级权限用 src/hooks/use-permission.ts 的 usePermission,React 里没有指令机制,权限裁剪就是条件渲染。
import { usePermission } from '@/hooks/use-permission'
export function GoodsToolbar({ onAdd }: { onAdd: () => void }) {
// 一屏调一次,把结果传下去;别在表格行里逐行调用(见下文)
const { permissions, hasPermission, hasAnyPermission } = usePermission()
return (
<>
{hasPermission('system:user:create') && <Button onClick={onAdd}>新增用户</Button>}
{hasPermission('system:user:import') && <Button variant="outline">导入</Button>}
{hasPermission('system:user:export') && <Button variant="outline">导出</Button>}
{hasAnyPermission(['system:user:resetPwd', 'system:user:updateRole']) && (
<Button variant="ghost">更多操作</Button>
)}
</>
)
}API 共三项(src/hooks/use-permission.ts:16)。
| 方法 | 语义 |
|---|---|
permissions | 当前权限码数组,需要传给子组件时直接用 |
hasPermission(code?) | 具备指定权限;不传码返回 true |
hasAnyPermission(codes) | 数组内任一权限具备即通过 |
两个使用要点:
- 每屏调一次,往下传。hook 内部订阅认证 store,在表格行的列定义里逐行调用会把一条订阅放大成 N 条。行的显隐裁剪把
permissions数组传进列工厂,行内只做数组比对(src/routes/(main)/(app)/system/user/-components/user-list.tsx:64的真实用法:页面调一次usePermission,再经createUserColumns(handleRowAction, rowOffset, permissions)传给列定义)。 - 返回的函数引用稳定。权限码不变时函数身份不变,可以作为
useMemo/useCallback的依赖放心使用。
「多个权限都具备才显示」(AND 语义)没有独立 API,用 codes.every(...) 组合 hasPermission 即可。
与后端的配合
前端权限控制只做展示层裁剪,真正的鉴权在后端:CRUD 控制器的 BaseController.preHandle 按请求方法与路径自动生成权限码并校验(POST /system/user 对应 system:user:create)。两边约定同一套权限码,新增 CRUD 页面时照 模块:资源:动作 的格式给按钮加条件渲染即可,不需要额外注册。
权限码在响应 403 时还有一道兜底:绕过前端裁剪直接发请求会被后端拒绝,HTTP 层把页面替换到 /unauthorized(见HTTP 请求)。
相关源码
- src/hooks/use-permission.ts:
usePermissionhook - src/lib/permission.ts:判定规则与通配约定
- src/stores/auth/auth-store.ts:权限数据的加载与生命周期
- src/routes/(main)/(app)/system/user/-components/user-list.tsx:权限裁剪的完整页面示例