Permix 就绪状态与事件系统:isReady 和 setup/ready/check 三大 Hook 详解
Permix 就绪状态与事件系统:isReady 和 setup/ready/check 三大 Hook 详解
Permix 是一个轻量、框架无关且类型安全的 TypeScript 权限管理库。在真实应用中,权限规则往往来自异步的用户信息或接口数据,这时就需要 Permix 的就绪状态判断(isReady() / isReadyAsync())和事件系统(setup、ready、check 三大 Hook)来告诉你的代码"权限什么时候能用、什么时候变了、每次校验发生了什么"。本文带你用最短的时间理解这两个机制,并给出避坑清单。
为什么需要"就绪"状态?
权限数据不可能总是"立刻就有"。典型场景:
- 组件挂载后才会请求到当前用户的角色信息,之后再执行
setup(); - SSR 应用中,服务端
dehydrate()出的状态传到客户端hydrate()后,还需要在客户端重新setup()才能恢复函数型规则。
在规则就绪之前调用 check() 或 dehydrate(),Permix 会抛出 PermixNotReadyError(定义见 errors.ts)。isReady() 就是你判断"现在能不能安全地做权限判断"的开关。
如何用 isReady 判断权限是否就绪
isReady():同步布尔值
实例只有经历过一次 setup()(或创建时通过 createPermix(initialRules) 传入了初始规则)才返回 true。特别注意:单独调用 hydrate() 不会让实例就绪。
console.log(permix.isReady()) // false
permix.setup({ post: { create: true, read: true } })
console.log(permix.isReady()) // true
isReadyAsync():可等待的 Promise
当规则在异步流程中设置时,用 await permix.isReadyAsync() 等待就绪后再 check(),非常适合路由中间件、useEffect 等场景:
await permix.isReadyAsync()
const canCreate = permix.check('post.create')
两者的内部实现位于 permix.ts:isReady() 直接读取内部 ready 标志,isReadyAsync() 则返回一个在首次 setup() 时被 resolve 的 Promise(若已就绪会立即完成)。
💡 一个容易忽略的细节:
hydrate()之后,布尔型规则立即可查(check()正常工作),但isReady()仍为false——直到客户端再次setup()。这是有意为之:帮助你在"忘记调用setup()"时暴露问题,而不是悄悄返回被折叠的权限。
三大 Hook 事件一览
Permix 通过 permix.hook() 和 permix.hookOnce() 注册事件处理器,共有三个事件,接口定义在 permix.ts:
| 事件 | 触发时机 | 典型用途 |
|---|---|---|
setup |
每次 setup() 或 hydrate() 后都触发 |
权限变化后刷新 UI、失效缓存 |
ready |
仅一次:实例首次就绪(首次 setup() 或初始规则) |
一次性引导逻辑,如关闭全局 loading 壳 |
check |
每次 check() 前触发,处理器收到 { path, data } 上下文 |
日志、埋点、调试权限判定 |
一句话选型口诀:UI 要跟着每次权限变化刷新就用 setup;只关心"第一次能用"就用 ready;想审计每次校验就用 check。
setup 事件:每次权限更新都会触发
// 每次 setup 执行都会调用(包括 hydrate)
permix.hook('setup', () => {
console.log('Permissions were updated')
})
注意 hydrate() 同样会触发 setup 事件——因为它本质上也是一次规则更新。测试用例 permix.test.ts 验证了连续两次 setup() 会让处理器被调用两次。
ready 事件:首次就绪只触发一次
ready 事件只在实例第一次变为就绪时触发:无论是首次 setup(),还是 createPermix() 时就传入了初始规则。之后的 setup() 不会再触发它,hydrate() 也不会。
permix.hook('ready', () => {
hideGlobalLoading() // 一次性引导逻辑
})
⚠️ 关键坑点:ready 处理器必须在首次 setup() 之前注册。如果在实例已经就绪之后才注册 hook('ready', ...),它将永远不会被调用。这一行为有明确的测试保障:permix.test.ts 断言连续两次 setup() 后 ready 处理器只被调用一次。
check 事件:监听每一次权限校验
check 事件在每次权限求值前触发,处理器能拿到被校验的路径和传入数据:
permix.hook('check', ({ path, data }) => {
console.log(`Checking permission: ${path}`, data)
})
permix.check('post.create') // Checking permission: post.create undefined
permix.check('post.edit', { authorId: '1' })
// Checking permission: post.edit { authorId: '1' }
两个细节:
- 使用回调形式
permix.check(c => c('post.create') && ...)时,path会是null; - 每次
check()的上下文对象由createCheckContext构造,随后才调用真正的求值逻辑,见 permix.ts。
hook 与 hookOnce:注册和注销的两种方式
| 方法 | 行为 | 返回值 |
|---|---|---|
permix.hook(name, fn) |
事件每次发生都执行 | 返回注销函数,调用后处理器移除 |
permix.hookOnce(name, fn) |
只执行一次,自动注销 | 无返回值 |
const remove = permix.hook('setup', () => refreshCache())
// 组件卸载时:
remove()
底层由通用的 createHooks 实现:hook 会把处理器推入对应事件的列表并返回移除函数,hookOnce 则用包装函数在执行后自动移除自己(见 hooks.ts)。执行时框架对监听列表做了浅拷贝,因此处理器在回调中注册/注销其他处理器是安全的。
SSR 实战:hydrate + setup 的正确顺序
SSR 场景下,"就绪"机制的价值最大(完整说明见 ready.mdx):
// 服务端
const state = serverPermix.dehydrate()
// 客户端
clientPermix.hydrate(state)
console.log(clientPermix.isReady()) // false —— 但布尔规则已可 check
console.log(clientPermix.check('post.read')) // 正常工作
clientPermix.setup({
post: { read: post => !!post?.isPublic }, // 恢复函数型规则
})
console.log(clientPermix.isReady()) // true,ready 事件此刻触发
推荐组合拳:
- 客户端
hydrate()后立即渲染,布尔规则保证首屏正确; - 用
await permix.isReadyAsync()或hook('ready', ...)等待函数型规则恢复完成,再放开依赖动态数据的交互。
常见坑与最佳实践清单
- 🧭
hydrate()≠ 就绪:只hydrate()会让isReady()保持false,务必在客户端补一次setup(); - 🧭
ready只有一次机会:引导类监听要提前注册,否则错过; - 🧭 别在没 setup 时就 check:会抛
PermixNotReadyError,提示语是Call setup() before using check() or dehydrate().; - 🧭 回调式
check()的path是null:写日志/埋点前先判空; - 🧭 组件化场景记得注销:
hook()返回的注销函数应绑定到组件卸载生命周期,避免内存泄漏。
更多细节可查阅官方指南:事件系统文档 与 就绪状态文档。掌握 isReady 与三大 Hook,你的 Permix 应用就能在异步、SSR、动态规则等复杂场景下依然行为可预期。