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

🥽 authHub 参数

属性	类型	描述	是否必传填
`env`	`development \| dev \| test \| uat \| prod`	环境设置	否默认`dev`
`hubUrl`	`string`	Hub URL	否默认`dev的hub`
`redirectUrl`	`string`	重定向 URL	否默认`dev的登录`
`whetherRedirect`	`boolean`	是否重定向	否默认`true`
`platform`	`aplus \| admin`	平台	否默认`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`	重定向到登录页面	无	`Promise<void>`

🚨 注意

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环境的登录中心，本地项目不在有登录模块