@aplus-frontend/aplus-auth-sdk

📋 目录

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

💁 介绍

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

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

⚙️ 快速开始

$3

``bash


在项目根目录中安装

pnpm add @aplus-frontend/aplus-auth-sdk

或使用 npm

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

或使用 yarn

yarn add @aplus-frontend/aplus-auth-sdk
`

$3

`typescript
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();
}
`

🔌 接入案例

- 登录中心

`ts
//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'});
`

- 客户端（应用端）

`ts
//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)
}
`
- 客户端自定义登录页地址
`ts
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 | 指定登录页所在环境地址，可以传入5个环境地址'development' \| 'dev' \| 'test' \| 'uat' \| 'prod' | 否 | false |
| redirectLoginExtraParams | Record | 重定向跳转到登录页需要额外携带的参数 | 否 | false |


📦️ API 方法

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


🚨 注意事项

- 初始化限制：
- 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' 错误

$3

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

$3

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

📜 更新日志

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