@aplus-frontend/aplus-auth-sdk
TypeScript icon, indicating that this package has built-in type declarations

2.0.2-beta.0 • Public • Published

@aplus-frontend/aplus-auth-sdk

NPM Version NPM Downloads NPM License

📋 目录

💁 介绍

aplus 前端项目登录 SDK,适用于 aplus 单体项目或微前端项目,提供便捷的登录认证功能和用户信息获取能力。本 SDK 通过 localStorage 存储认证信息,简化了不同平台间的鉴权逻辑,让开发者无需关心复杂的认证流程。

主要功能

  • 多平台支持:适配 aplus、admin、quick、word、doc 等多种平台
  • 自动认证:检测 token 有效性,实现登录状态维护
  • 统一接口:提供用户信息、菜单、权限等统一获取方式
  • 智能重定向:根据配置自动处理登录流程和页面跳转
  • URL 参数处理:方便获取和解析 URL 参数

⚙️ 快速开始

安装

# 在项目根目录中安装
pnpm add @aplus-frontend/aplus-auth-sdk

# 或使用 npm
npm install @aplus-frontend/aplus-auth-sdk

# 或使用 yarn
yarn add @aplus-frontend/aplus-auth-sdk

基本使用

import { authHub } from '@aplus-frontend/aplus-auth-sdk';
import { markRaw } from 'vue'; // 如果在 Vue 3 中使用

// 创建认证实例(在 Vue 3 中需要使用 markRaw)
const authClient = markRaw(authHub({
  platform: 'aplus',  // 平台类型
  env: 'dev',         // 环境
  apiUrl: 'https://api.example.com',
  urlPrefix: '/api'
}));

// 初始化认证
 await authClient.init();
if (token) {
  // 用户已登录,可以获取用户信息
  const userInfo = await authClient.getUserInfo();
  const menus = await authClient.getUserMenus();
  const permissions = await authClient.getUserPermissions();
}

🔌 接入案例

  • 登录中心
//vue3 项目 main.ts中

import { authHub, authClass } from '@aplus-frontend/aplus-auth-sdk';
//初始化链接
const authClient = authHub({
  platform: 'aplus',
  used: 'login', //指明用途
  env: import.meta.env.MODE,
  debug: true,
  apiUrl: import.meta.env.VITE_GLOB_API_URL,
  urlPrefix: import.meta.env.VITE_GLOB_API_URL_PREFIX
});
//用途是login,init什么都不返回
await authClient.init();
const token = await get_token_from_request();
//这里是一些登录请求逻辑
//成功之后设置token
await authClient?.setAuthToken(res.token,{locale:'zh-CN'});
  • 客户端(应用端)
//vue3 项目 main.ts中

import { authHub, authClass } from '@aplus-frontend/aplus-auth-sdk';
//初始化链接
authClient = authHub({
  platform: 'aplus',
  used: 'site', //指明用途
  env: import.meta.env.MODE,
  debug: true,
  apiUrl: import.meta.env.VITE_GLOB_API_URL,
  urlPrefix: import.meta.env.VITE_GLOB_API_URL_PREFIX
});
//初始化
await authClient.init();
const token = await this.authClient.getAuthToken();
if (token) {
  console.log('token:', token);
}
const userInfo = await authClient.getUserInfo();
if (userInfo) {
  console.log('userInfo:', userInfo);
}

const menus = await authClient.getUserMenus();
if (menus) {
  console.log('menus:', menus);
}

const permissions = await authClient.getUserPermissions();
if (permissions) {
  console.log('permissions:', permissions);
}
//获取url上的语言
const locale = await authClient.getUrlParam('locale')
if(locale){
  //lang zh_CN
  console.log('locale',locale)
}

🥽 配置参数

参数 类型 描述 必填 默认值
env 'development' | 'dev' | 'test' | 'uat' | 'prod' 环境设置,决定使用哪个环境的登录中心 'dev'
platform 'aplus' | 'admin' | 'quick' | 'word' | 'doc' 平台类型,指定当前应用类型 'aplus'
used 'login' | 'site' 用途类型:
- 'login':登录中心
- 'site':业务应用
'site'
apiUrl string API 请求基础 URL,用于与后端通信 --
urlPrefix string API URL 前缀,与 apiUrl 组合形成完整请求路径 --
redirectUrl string 重定向 URL,未登录时跳转的登录页面 根据环境和平台自动设置
defaultRedirectUrl string 默认重定向 URL,当没有地址栏不存在redirectUrl时使用,例如在登录页重定向地址被手动删掉之后,需要跳转的平台地址 -
whetherRedirect boolean 是否自动重定向,若为 false 则需自行处理重定向逻辑 true
debug boolean 调试模式,开启后会打印详细日志,并在重定向前暂停(使用debugger) false

📦️ API 方法

方法名 描述 参数 返回值 行为
init 初始化认证中心 Promise<void> -
redirectLogin 重定向到登录页面 records?: Record<string, any> Promise<void> - 清除当前token
- 将当前页面URL作为参数传递给登录页面
- records参数会被追加到重定向URL中
- 清空浏览器历史记录
redirectTargetUrl 重定向到指定业务页面 url: string
records?: Record<string, any>
Promise<void> - 跳转到指定URL
- records参数会被转换为URL参数
- 清空浏览器历史记录
getUrlParam 获取URL上的指定参数 name: string Promise<string | null> - 优先从查询字符串获取
- 然后从哈希参数中获取
- 支持解析嵌套URL中的参数
- 支持解码URL
getAuthToken 获取认证token Promise<string> - 从localStorage读取token
- 如果不存在则返回空字符串
setAuthToken 设置认证token token: string
records?: Record<string, any>
Promise<void> - 将token存储在localStorage
- usedloginwhetherRedirect=true时会自动重定向到业务应用:
  - 优先使用URL中的redirectUrl
  - 其次使用defaultRedirectUrl
  - records参数会被追加到重定向URL
isHasAuthToken 检查是否有认证token Promise<boolean> - 检查token是否存在
- 返回布尔值表示结果
isLegalToken 检查token是否合法 Promise<boolean> - 通过调用后端接口验证token有效性
- 返回布尔值表示结果
removeAuthToken 移除认证token Promise<{ code: number; message: string }> - 从localStorage中清除token
- 返回操作结果
getUserInfo 获取用户信息 Promise<CurrentUserInfo | void> - 调用后端接口获取用户信息
- 如果token无效则跳转登录页
getUserMenus 获取用户菜单 Promise<UserMenus | void> - 调用后端接口获取用户菜单
- 如果token无效则跳转登录页
getUserPermissions 获取用户权限 Promise<UserButton | void> - 调用后端接口获取用户权限
- 如果token无效则跳转登录页

🚨 注意事项

  • 初始化限制

    • init 方法在每个 authClass 实例中只能调用一次,重复调用会抛出错误
    • 在 Vite 热重载的开发环境下可能会出现 init方法已经被调用过 的提示,这是正常现象
  • 使用场景

    • used'login' 时,init 不会返回任何值
    • used'site' 时,若已登录则返回 token,否则会执行重定向(除非设置 whetherRedirect: false
    • setAuthToken 方法应在登录接口成功后调用,用于设置用户的认证 token
  • 重定向行为

    • redirectLoginredirectTargetUrl 方法会清空浏览器历史记录并执行重定向
  • Vue 整合

    • 使用 Vue 3 时,需要用 markRaw() 包装 authHub 实例,防止 Vue 对其进行响应式代理
    • 如不这样做,可能遇到 Failed to read a named property '__v_isRef' from 'Window' 错误

工作流程

SDK 主要通过 localStorage 存储和访问认证信息,根据配置的 used 参数支持两种使用场景:

  1. 应用场景 (used: 'site')

    • 初始化流程:
      1. 检查 URL 中是否有 token 参数,有则保存并移除参数
      2. 检查本地 token 是否存在及是否有效
      3. 若 token 有效,返回 token 供应用使用
      4. 若 token 无效或不存在且 whetherRedirect: true,则重定向到登录页面
  2. 登录场景 (used: 'login')

    • 初始化流程:
      1. 不执行任何验证或重定向操作
      2. 提供 setAuthToken 方法供登录成功后调用
    • 登录成功后:
      1. 调用 setAuthToken 设置 token
      2. 检查 URL 中的 redirectUrl 参数或 defaultRedirectUrl 配置
      3. 自动重定向回原应用页面

存储机制

  • 认证信息存储在 localStorageauthToken 键下
  • 存储格式为 JSON 对象:{ [platform]: { token: "xxx" } }
  • 不同平台介入使用不同的platformkey!!!否则容易互相覆盖token!
  • 支持多平台独立存储 token,不同平台互不影响

📜 更新日志

查看完整的更新历史,请参阅 CHANGELOG.md

Package Sidebar

Install

npm i @aplus-frontend/aplus-auth-sdk

Weekly Downloads

431

Version

2.0.2-beta.0

License

MIT

Unpacked Size

39.1 kB

Total Files

5

Last publish

Collaborators

  • hemuxue
  • lonelyfkinging
  • huimin2000
  • rainiexxx
  • huaz
  • ollieliu
  • limoer
  • asd517665931
  • zxlin429
  • kuguago
  • chopinnn
  • wolfcq