Permix 就绪状态与事件系统:isReady 和 setup/ready/check 三大 Hook 详解

原创2026-11-09 12:22:301,990 阅读

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 事件此刻触发

推荐组合拳:

  1. 客户端 hydrate() 后立即渲染,布尔规则保证首屏正确;
  2. 用 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、动态规则等复杂场景下依然行为可预期。

登录后查看全文
permix