@aplus-frontend/aplus-auth-sdk

@aplus-frontend/aplus-auth-sdk

📋 目录

• 介绍
• 快速开始
• 接入案例
• 配置参数
• API 方法
• 注意事项
• 更新日志

💁 介绍

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)
}

• 客户端自定义登录页地址

const authClient3 = authHub({
  platform: 'tenant-app',
  used: 'site',
  env: 'dev',
  apiUrl: 'https://api.example.com',
  urlPrefix: '/api',
  customRedirectUrls: {
    dev: 'https://dev-custom-login.example.com',
    test: 'https://test-custom-login.example.com',
    prod: 'https://prod-custom-login.example.com'
  }
});

🥽 配置参数

参数	类型	描述	必填	默认值
env	'development' | 'dev' | 'test' | 'uat' | 'prod'	环境设置，决定使用哪个环境的登录中心	否	'dev'
platform	'aplus' | 'admin' | 'quick' | 'word' | 'doc'| 'string'	平台类型，指定当前应用类型,可以是指定的文档中的类型，也可以是任意字符串，自定义平台，该字段影响存储token的key	是	'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
customRedirectUrls	Record<env,string>	指定登录页所在环境地址，可以传入5个环境地址'development' | 'dev' | 'test' | 'uat' | 'prod'	否	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 - used为login且whetherRedirect=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无效则跳转登录页
getAppInfo	获取应用信息	无	Promise<AppInfoRes | void>	- 调用后端接口获取用于信息 - 如果token无效则跳转登录页

🚨 注意事项

• 初始化限制：

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

• 使用场景：

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

• 重定向行为：

  • redirectLogin 和 redirectTargetUrl 方法会清空浏览器历史记录并执行重定向

• Vue 整合：

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

工作流程

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

• 应用场景 (used: 'site')：

  • 初始化流程：
    • 检查 URL 中是否有 token 参数，有则保存并移除参数
    • 检查本地 token 是否存在及是否有效
    • 若 token 有效，返回 token 供应用使用
    • 若 token 无效或不存在且 whetherRedirect: true，则重定向到登录页面

• 登录场景 (used: 'login')：

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

存储机制

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

📜 更新日志

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