@aplus-frontend/aplus-auth-sdk

@aplus-frontend/aplus-auth-sdk

💁 介绍

aplus前端项目登录SDK，适用于aplus单体项目或者微前端项目，提供快速接入登录功能，无需在鉴权的业务逻辑担心。

⚙️ 快速开始

  #根路径加 -w
  pnpm add @aplus-frontend/aplus-auth-sdk

🔌 接入案例

• 登录中心

//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();
//这里是一些登录请求逻辑
//成功之后设置token
await authClient?.setAuthToken(res.token);

🚨 注意

• authHub内部会动态插入iframe,vue会报错SecurityError: Failed to read a named property '__v_isRef' from 'Window',解决就是authHub外层包markRaw，禁止vue代理响应式对象

• 客户端（应用端）

//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
});
//用途是site init会返回token
const token = await authClient.init();
console.log('token:', token);
if (token) {
  tokenRef.value = 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 lang = await authClient.getUrlParam('lang')
if(lang){
  //lang zh_CN
  console.log('lang',lang)
}

🥽 authHub 参数

属性	类型	描述	是否必传填
env	development | dev | test | uat | prod	环境设置	否 默认dev
hubUrl	string	Hub URL	否 默认dev的hub
redirectUrl	string	重定向 URL	否 默认dev的登录
whetherRedirect	boolean	是否重定向	否 默认true
platform	aplus | admin | quick	平台	否 默认aplus
used	login | site	用途类型	否 默认site
debug	boolean	调试模式,建议仅在开发环境开启，重定向地址之前会暂停	否 默认false
maxRetries	number	最大重试次数	否 默认3
apiUrl	string	API URL	是 建议直接设置import.meta.env.VITE_GLOB_API_URL
urlPrefix	string	URL 前缀	是 建议直接设置import.meta.env.VITE_GLOB_API_URL_PREFIX

📦️ authHub 方法

方法名	描述	参数	返回值
init	初始化认证中心,used为site时候初始化后，如果已经登录返回token，未登录自定跳转登录页,可以设置whetherRedirect为false关闭自动跳转。used为login时候不返回任何值	options: UserConfig	Promise<string | void>
getAuthToken	获取认证 token	无	Promise<string>
setAuthToken	设置认证 token，used为login时候自动跳转应用,设置whetherRedirect为false关闭自动跳转	token: string	Promise<void>
isHasAuthToken	检查是否存在认证 token	无	Promise<boolean>
isLegalToken	检查 token 是否合法	无	Promise<boolean>
removeAuthToken	移除认证 token	无	Promise<{ code: number; message: string }>
getUserInfo	获取用户信息	无	Promise<CurrentUserInfo | void>
getUserMenus	获取用户菜单	无	Promise<UserMenus | void>
getUserPermissions	获取用户权限	无	Promise<UserButton | void>
redirectLogin	重定向到登录页面,可选参数records对象作为跳转到登录页需要拼接的参数	records?:Record<string, any>	Promise<void>
redirectUrl	重定向到某个特定业务页面,url为必选，可选参数records对象作为跳转到特定页需要拼接的参数	url: string;records?: Record<string, any>	Promise<void>
getUrlParam	获取url上的指定参数	name: string	Promise<string | null>

🚨 注意

• init 方法在 used 为 'login' 时不会返回任何值,为site时会返回token。另外开发环境下，因为vite热重载会提示报错:init方法已经被调用过这是正常现象。
• setAuthToken 方法需要在登录接口成功后再调用，以设置用户的认证 token。
• redirectLogin 方法会清空浏览器历史记录并重定向到登录页面。

原理介绍

不同源的域名是如何共享数据的？答案就是iframe的postMessage实现跨域共享数据，包里依赖了cross-storage这个lib。

@aplus-frontend/aplus-auth-sdk用途有两个应用场景一个是site,另一个是login,当场景是site时候链接hub共享中心（动态插入iframe hub.html）,init方法检测hub中是否存在token是否过期，过期会自动跳转登录页面，当然也可以手动关掉whetherRedirect等于false,这样设置的话需要自己重定向逻辑。当场景是login时候表示是登录界面需要接入,init方法什么都不返回，调用真正的登录接口后需要调用setAuthToken把真正的token设置到hub.html中。注意：如何使用了React或vue3框架，authHub是一个带有副作用的函数,需要结合框架的生命周期调用。init方法中hub.html的地址被预设了4个环境，如果有特殊需求，也可以通过hubUrl自行设置。

🚨 注意

2024年1月25日在高版本Chrome115中启用了存储分区，简单来说example.com通过iframe方式嵌入a.com和b.com中访问的localstorage是不同的存储分区，所有跨域名的存储共享数据失效了。查看原因 所以使用cross-storage不能直接解决问题，需要配合同源策略。

aplus本地开发指南设置

1. 修改本地host文件

  #windows电脑 C:\Windows\System32\drivers\etc\hosts

  #mac  sudo vi /etc/hosts

  #hosts文件中加入下面这行

  127.0.0.1 aplus.elnkpro.com

2. 修改vite代理配置

  //vite.config.ts

  server: {
      port: 4009,
      host: 'aplus.elnkpro.com',
      trictPort: true,
      proxy: {
        '/api': {
          target: 'http://api.dev.elnkpro.com',
          changeOrigin: true,
          rewrite: (path) => path.replace(/^\/api/, '')
        }
      }
    }

3. 本地开发访问网址

http://aplus.elnkpro.com:4009/

经过以上这置位于本地localhost:4009的项目可以使用dev环境的登录中心，本地项目不在有登录模块