@composy/auth-vue

@composy/auth-vue

English

@composy/auth-vue 是 @composy/auth-core 的 Vue 3 适配层，负责：

• 原生 Vue plugin 安装。
• @composy/engine-vue 插件安装。
• composables、指令与组件封装。
• 将 AuthManager 注入 Vue 应用并与路由守卫联动。

✨ 核心能力

• 双插件接入：createAuthPlugin() 原生 Vue 插件与 createAuthEngineVuePlugin() engine 插件复用同一套 installAuthIntegration() 安装路径，行为完全一致
• 全量 composables：useAuth / useUser / useLogin / useSession / useToken / usePermission 覆盖认证各环节；授权检查通过 AuthConfig.permission 委托给 Permission Runtime
• 共享状态桥接：同一 AuthManager 的多个 composable 复用一份状态订阅与倒计时；最后一个 Vue effect scope 卸载时自动释放订阅和定时器，重新挂载时复用缓存桥接
• 路由守卫去重与释放：通过 WeakMap<Router, WeakSet<AuthManager>> 防止重复注册，并在 App 卸载时移除守卫、恢复 globalProperties
• 权限指令：内置 vPermission 指令与 createPermissionDirective() 工厂
• 开箱组件：AuthRequired 组件提供认证兜底 UI

当前结构

• plugin：原生 Vue plugin、engine plugin、路由守卫、注入键、安装流程。
• composables：useAuth、useUser、usePermission、useLogin、useSession、useToken。
• composables/shared：共享状态桥接与注入管理器解析。
• directives：权限指令。
• components：认证相关组件。
• engine：engine 状态键导出。

设计重点

• 原生 Vue plugin 与 engine plugin 复用同一套 installAuthIntegration() 安装逻辑，行为保持一致。
• 同一个 AuthManager 只创建一个状态桥接层，多个 composable 共享订阅与定时器；最后一个 Vue effect scope 卸载时释放桥接资源，重新挂载后复用缓存桥接，减少空闲轮询与重复响应式开销。
• 路由守卫通过 WeakMap<Router, WeakSet<AuthManager>> 去重，避免重复注册。

安装

pnpm add @composy/auth-vue @composy/auth-core vue

如果需要自动路由守卫，再安装 vue-router。

原生 Vue plugin 用法

import { createRestAuthServices } from '@composy/auth-core/adapters'
import { createAuthPlugin } from '@composy/auth-vue/plugin'
import { createApp } from 'vue'
import { createRouter } from 'vue-router'
import App from './App.vue'

const app = createApp(App)
const router = createRouter({ history, routes })

const authPlugin = createAuthPlugin({
  services: createRestAuthServices({
    baseURL: '/api/v1',
  }),
  loginRoute: '/login',
  defaultRoute: '/dashboard',
  whiteList: ['/login'],
})

app.use(authPlugin, { router })
app.mount('#app')

同一个 AuthPlugin 安装到多个 Vue App 时，每个 App 默认创建独立的 AuthManager；只有通过 manager 显式注入时才共享实例。插件会在安装时绑定 services 并调用 manager.init()，App 卸载时释放路由守卫和插件自有 manager；外部传入的 manager 不会被销毁。

也可以直接把 router 放到 createAuthPlugin({ router }) 中。

@composy/engine-vue 插件用法

import { createRestAuthServices } from '@composy/auth-core/adapters'
import { createAuthEngineVuePlugin } from '@composy/auth-vue/plugin'
import { createVueEngine } from '@composy/engine-vue'
import App from './App.vue'

const engine = createVueEngine({
  app: {
    rootComponent: App,
  },
  plugins: [
    createAuthEngineVuePlugin({
      services: createRestAuthServices({
        baseURL: '/api/v1',
      }),
    }),
  ],
})

await engine.mount('#app')

安装后，插件会把认证状态同步到 engine state，并发出登录、登出、用户更新、Token 刷新等事件。

composables 示例

import { useAuth, useUser } from '@composy/auth-vue/composables'

const auth = useAuth()
const user = useUser()

await auth.login({
  username: 'admin',
  password: '123456',
})

console.info(user.user.value?.username)

usePermission、vPermission、AuthRequired 的权限条件和 Router permission guard 都通过 AuthConfig.permission 查询授权。请在创建插件或 AuthManager 时注入 Permission adapter；未注入时，适配器抛错或返回非布尔值时，非空权限/角色检查默认拒绝，不会从 User.roles 或 User.permissions 自行推断授权。适配器必须同步返回布尔值。

自定义 onLogin、onRefreshToken、onFetchUser 和 onLogout handler 可以继续使用原有参数，也可以接收最后一个 AuthOperationContext 参数，用于感知当前 generation 和取消信号。Vue 包的稳定、兼容、弃用、实验和内部 API 清单见 PUBLIC-API.md。

AuthPluginOptions 继承 Core 的 lifecycle 配置；传入 createBrowserAuthLifecycle() 后，插件创建的 AuthManager 会在页面隐藏或离线时暂停自动刷新。同时继承 eventPort、diagnosticSink 与 session.deviceInfoProvider，可由宿主接入统一的事件、诊断和设备能力；这些 Port 的异常不会回滚已提交的认证事实。Core 还导出 AuthSecretStore 与 AuthCryptoAdapter 类型，便于在 Vue 应用中复用宿主的存储和密钥实现。

主要导出

• @composy/auth-vue/plugin
  • createAuthPlugin
  • createAuthEngineVuePlugin
  • createAuthGuard
  • setupRouterGuard
  • createAuthManagerFromOptions
• @composy/auth-vue/composables
  • useAuth
  • useLogin
  • usePermission
  • useSession
  • useToken
  • useUser
• @composy/auth-vue/directives
  • vPermission
  • createPermissionDirective
• @composy/auth-vue/components
  • AuthRequired

🔨 构建产物与验证

• 使用 @composy/builder 构建，产出 es（ESM + 类型）、esm、lib（CJS）与 dist/index.min.js CDN 产物；样式以 Less 编写，构建后处理会把 es / lib 内的相对 *.less 编译为 *.css。
• 类型检查使用 vue-tsc --noEmit。
• ESLint、TypeScript 和 @composy/builder 的权威配置均位于本包 .ldesign/ 目录；根目录同名配置保留为兼容入口。

pnpm build        # 完整构建：builder 构建 + 产物归一 + 校验
pnpm type-check   # vue-tsc --noEmit
pnpm test:run     # 单元测试（ltesting run:unit）
pnpm test:consumer # 发布入口 TypeScript consumer 检查
pnpm lint:check   # ESLint 校验

相关文档

• 工作区总览
• core 包说明