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 |
方法名 | 描述 | 参数 | 返回值 | 行为 |
---|---|---|---|---|
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无效则跳转登录页 |
-
初始化限制:
-
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'
错误
- 使用 Vue 3 时,需要用
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" } }
- 不同平台介入使用不同的
platform
key!!!否则容易互相覆盖token! - 支持多平台独立存储 token,不同平台互不影响
查看完整的更新历史,请参阅 CHANGELOG.md。