Permix 前端框架集成一览:Vue、Solid、Svelte 权限响应式开发一篇搞定
Permix 前端框架集成一览:Vue、Solid、Svelte 权限响应式开发一篇搞定
Permix 是一个轻量、框架无关、类型安全(type-safe)的权限管理库,为 TypeScript 应用提供客户端与服务端统一的权限方案。本文带你一次搞定 Permix 在 Vue、Solid、Svelte 三大前端框架中的响应式集成:从实例创建、Provider 注入,到 usePermix Hook 与 Check 组件用法,一篇讲透。
为什么前端需要 Permix?
传统写法里,if (user.role === 'admin') 这类判断散落在各个组件中,既难维护也难做类型检查。Permix 用一次 createPermix<...>() 定义权限 Schema,之后:
- ✅ 100% 类型安全:
check('post.edit')写错路径直接报编译错误 - ✅ 单一数据源:前后端共用同一份权限定义
- ✅ 零依赖:核心 gzip 仅约 2.64 kB(各框架适配器再增加约 0.8–2.2 kB)
- ✅ 响应式:权限变更后 UI 自动更新,无需手动刷新
核心 API 在 permix/src/core/permix.ts,各框架只是薄薄的一层适配器。
三步准备:安装与创建实例
无论用哪个框架,准备工作完全一致:
pnpm add permix
// lib/permix.ts
import { createPermix } from 'permix'
export const permix = createPermix<{
post: [
'read',
{ name: 'edit', type: Post }, // 绑定实体类型,可做对象级判断
]
}>()
export function setupPermix(user: User) {
return permix.setup({
post: {
read: true,
edit: post => post?.authorId === user.id, // 函数规则:对象级权限
},
})
}
💡 规则既可以是布尔值,也可以是回调函数——函数能拿到实体数据做细粒度判断(比如"只有作者能编辑自己的文章")。
Vue 集成指南:PermixProvider 与 usePermix 组合式 API
1. 注入 Provider:用 PermixProvider 包裹应用根组件(源码见 permix/src/vue/components.ts):
<script setup lang="ts">
import { PermixProvider } from 'permix/vue'
import { permix } from './lib/permix'
</script>
<template>
<PermixProvider :permix="permix">
<YourApp />
</PermixProvider>
</template>
2. 使用 usePermix 组合式函数:返回响应式的 check 方法与 isReady computed,权限一变,v-if 立即跟着变(实现见 permix/src/vue/composables.ts):
<script setup lang="ts">
const { check, isReady } = usePermix(permix)
</script>
<template>
<div v-if="!isReady">加载权限中...</div>
<button v-else-if="check('post.edit', post)">编辑文章</button>
</template>
3. 模板派:Check 组件:通过 createComponents(permix) 生成类型安全的 Check 组件,支持 path、data、reverse 属性与 #otherwise 插槽:
<Check path="post.edit" :data="post">
可编辑
<template #otherwise>无权限</template>
</Check>
📚 完整示例见 examples/vue/,官方文档:docs/content/docs/integrations/vue.mdx
Solid 集成教程:细粒度响应式权限 Hook
Solid 的适配器 API 与 Vue 几乎同名(源码见 permix/src/solid/hooks.ts),但响应式模型不同——isReady 是一个函数签名的 getter,调用时读取最新状态:
import { PermixProvider, usePermix } from 'permix/solid'
// 1. 根组件注入
<PermixProvider permix={permix}>
<YourApp />
</PermixProvider>
// 2. 组件内检查权限
const { check, isReady } = usePermix(permix)
const canEdit = () => check('post.edit', post)
return isReady()
? canEdit() ? <button>编辑</button> : <p>无权限</p>
: <div>加载中...</div>
Check 组件在 Solid 中通过 otherwise 属性(JSX 元素)表达兜底内容,权限变化由 Solid 的细粒度信号驱动,只重算真正变化的节点:
<Check path="post.edit" data={post} otherwise={<p>无权限</p>}>
可编辑
</Check>
📚 完整示例见 examples/solid/,官方文档:docs/content/docs/integrations/solid.mdx
Svelte 集成实战:基于 Runes 的响应式权限
Svelte 适配器要求 Svelte 5,基于 Runes 实现($state + $effect),源码见 permix/src/svelte/context.svelte.ts:
<script lang="ts">
import { PermixProvider } from 'permix/svelte'
import { permix } from './lib/permix'
let { children } = $props()
</script>
<PermixProvider {permix}>
{@render children()}
</PermixProvider>
Hook 用法有一个关键陷阱:usePermix 返回的 isReady 是响应式 getter,请直接在返回对象上访问(如 permissions.isReady),不要解构,否则会丢失响应性:
<script lang="ts">
const permissions = usePermix(permix)
</script>
{#if !permissions.isReady}
加载中...
{:else if permissions.check('post.edit', post)}
<button>编辑</button>
{/if}
Check 组件在 Svelte 中用 snippet 表达 otherwise 兜底内容(组件源码 permix/src/svelte/Check.svelte):
<Check path="post.edit" {data}>
可编辑
{#snippet otherwise()}无权限{/snippet}
</Check>
📚 完整示例见 examples/svelte/,官方文档:docs/content/docs/integrations/svelte.mdx
三大框架速查对比表
| 维度 | Vue | Solid | Svelte(需 v5) |
|---|---|---|---|
| 入口 | permix/vue |
permix/solid |
permix/svelte |
| 注入方式 | <PermixProvider :permix="permix"> |
<PermixProvider permix={permix}> |
<PermixProvider {permix}> |
| Hook | usePermix 组合式函数 |
usePermix Hook |
usePermix(Runes) |
isReady 形态 |
computed(模板内自动解包) | 函数签名 isReady() |
响应式 getter(勿解构) |
| Check 兜底 | #otherwise 插槽 |
otherwise JSX 属性 |
{#snippet otherwise()} |
| 适配器体积(gzip) | 0.87 kB | 0.82 kB | ≈2.17 kB |
⚠️ 三个框架都要遵守同一条铁律:Provider 与 Hook 必须传入同一个 permix 实例,否则类型安全与响应式都会失效。
SSR 场景:PermixHydrate 权限水合
三个框架都内置 PermixHydrate 组件。服务端渲染时用 permix.dehydrate() 序列化权限状态,客户端用 PermixHydrate 恢复,再调用 setup() 还原函数规则(函数无法序列化,脱水后会被转为 false)。详见 docs/content/docs/guide/hydration.mdx:
<PermixProvider permix={permix}>
<PermixHydrate state={dehydratedState}>
<YourApp />
</PermixHydrate>
</PermixProvider>
常见问题与最佳实践
- 忘记 Provider 会怎样? Hook 会直接抛出
Looks like you forgot to wrap your app with <PermixProvider>提示,属于刻意的快速失败设计。 - 如何减少样板代码? 仿照示例封装一层
usePermissions()(如 examples/vue/src/composables/permissions.ts),内部统一返回usePermix(permix)。 - 权限没变? 确认你在拿到用户/会话后调用了
permix.setup(...),并且isReady为真后再读取结果。 - 想用对象级权限? 在 Schema 里给权限声明实体类型(
{ name: 'edit', type: Post }),check第二参数会自动获得精确类型提示。
小结
Permix 的前端集成遵循统一心智模型:创建实例 → Provider 注入 → Hook/Check 检查,三个框架的 API 形态一致,只是响应式细节略有差异。配合类型安全的 Schema 与内置 SSR 水合,你只需几行代码就能让权限检查在整个前端应用中"活"起来。
下一步可以继续了解 快速上手指南 与服务端集成(Express、Fastify、Hono 等),实现前后端权限的完整闭环。