Permix 前端框架集成一览:Vue、Solid、Svelte 权限响应式开发一篇搞定

原创2026-11-09 14:26:391,988 阅读

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 等),实现前后端权限的完整闭环。

登录后查看全文
permix