@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 | | redirectLoginExtraParams | Record<string,any> | 重定向跳转到登录页需要额外携带的参数 | 否 | false |

📦️ API 方法

| 方法名 | 描述 | 参数 | 返回值 | 行为 | |-------|------|------|--------|------| | init | 初始化认证中心 | 无 | Promise<void> | - | | redirectLogin | 重定向到登录页面 | records?: Record<string, any> | Promise<void> | - 清除当前token- 将当前页面URL作为参数传递给登录页面- records参数会被追加到重定向URL中- 清空浏览器历史记录 | | redirectTargetUrl | 重定向到指定业务页面 | url: stringrecords?: 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: stringrecords?: 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 参数支持两种使用场景：

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. 自动重定向回原应用页面

存储机制

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

📜 更新日志

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