微前端基础类型库 (@skyfox2000/microbase)

项目概述

这是一个专为微前端架构设计的基础类型库，提供了微前端应用间通信、数据类型定义、路由管理和模块加载等核心功能。该库是微前端生态系统的基础组件，为主应用和子应用之间的协作提供标准化的接口和数据结构。

核心特性

🔗 微前端通信

• 统一通讯方式：所有API调用统一使用 forceDispatch 发送 + addDataListener 监听响应
• 类型安全调用：提供 mainAppApis 类型安全的API接口
• Promise支持：所有API调用返回Promise，支持async/await语法
• 环境检测：自动检测当前运行环境（独立应用/微应用/基座应用）

📋 类型定义体系

• 应用信息类型：完整的应用元数据类型定义
• 用户信息类型：用户认证和权限相关类型
• 主机信息类型：环境配置和服务地址类型
• 设置信息类型：前端配置和偏好设置类型

🛠 工具函数集合

• 数据处理：参数组合、数据转换等工具函数
• 环境管理：环境变量统一管理和配置
• 路由加载：动态路由加载和管理
• 模块加载：支持动态模块加载和组件注册

安装使用

安装方式

npm install -S @skyfox2000/microbase

基本使用

import { 
  isMicroApp, 
  initMainAppData, 
  initMicroAppProxy,
  mainAppApis,
  AppInfo,
  UserInfo 
} from '@skyfox2000/microbase';

// 检测是否在微应用环境中运行
if (isMicroApp()) {
  // 初始化微应用通讯层（包含数据监听和请求代理）
  initMainAppData();
  initMicroAppProxy();
  
  // 使用类型安全的API接口
  const userInfo = await mainAppApis.getUserInfo();
  console.log('当前用户:', userInfo);
  
  // 或使用通用调用方法
  const hostInfo = await mainAppApis.call<HostInfo>('getHostInfo');
}

API 文档

环境检测函数

isMicroApp(): boolean

检测当前应用是否运行在微前端环境中

if (isMicroApp()) {
  console.log('运行在微前端环境');
}

isBaseMicroApp(): boolean

检测当前应用是否为微前端基座应用

if (isBaseMicroApp()) {
  console.log('当前是基座应用');
}

主应用通信

initMainAppData(): void

初始化主应用数据，获取初始页面地址等信息

// 在微应用启动时调用
initMainAppData();

initMicroAppProxy(): void

初始化微应用通讯层，设置数据监听和请求代理

// 在微应用启动时调用，必须在 initMainAppData 之后
initMicroAppProxy();

mainAppApis - 主应用开放API接口

mainAppApis 提供了所有主应用API的类型安全调用方法：

// 获取主机信息
const hostInfo = await mainAppApis.getHostInfo();

// 获取应用信息
const appInfo = await mainAppApis.getAppInfo();

// 获取用户信息
const userInfo = await mainAppApis.getUserInfo();

// 获取授权令牌
const token = await mainAppApis.getToken();

// 获取设置信息
const settingInfo = await mainAppApis.getSettingInfo();

// 用户登录
const loginResult = await mainAppApis.userLogin({
  UserName: 'admin',
  UserPass: 'password'
});

// 用户登出
await mainAppApis.userLogout();

// 路由跳转
await mainAppApis.mainAppPush('/target-path');

callMainAppApi - 通用API调用

用于调用未预定义的API方法：

import { callMainAppApi } from '@skyfox2000/microbase';

// 通用调用
const result = await callMainAppApi('customMethod', { param1: 'value1' });

// 带类型的调用
const typedResult = await callMainAppApi<CustomType>('customMethod', params);

// 带超时的调用（默认30000ms）
const result = await callMainAppApi('longRunningMethod', params, 60000);

环境配置

EnvConfig: { [key: string]: string }

统一的环境变量配置对象

initEnv(metaEnv: ImportMetaEnv): void

初始化环境变量配置

import { initEnv } from '@skyfox2000/microbase';

// 在应用启动时初始化环境变量
initEnv(import.meta.env);

数据处理工具

combineParams(params: any): any

参数组合和处理工具函数

import { combineParams } from '@skyfox2000/microbase';

const combinedParams = combineParams({
  param1: 'value1',
  param2: 'value2'
});

路由管理

LoaderRouter

动态路由加载器，支持路由的动态注册和管理

import { LoaderRouter } from '@skyfox2000/microbase';

// 使用路由加载器
const router = new LoaderRouter(routeConfig);

模块加载

模块加载器函数

import { 
  loadModule, 
  initModuleLoader,
  moduleAttrs,
  moduleUrl,
  moduleRecords,
  moduleCom 
} from '@skyfox2000/microbase';

// 初始化模块加载器
initModuleLoader(import.meta.glob('./views/**/*.vue', { eager: false }));

// 动态加载模块
await loadModule('module-name');

类型定义

AppInfo - 应用信息

interface AppInfo {
  readonly Id: string;           // 应用唯一标识
  readonly Name: string;         // 应用名称
  readonly AppCode: string;      // 应用编码（路由前缀）
  readonly Version: string;      // 版本号
  readonly Icon: string;         // 应用图标
  readonly Source: AppSource;    // 应用来源
  readonly Action: AppAction;    // 应用动作类型
  readonly Host: string;         // 应用加载地址
  readonly Enabled: boolean | number; // 启用状态
  Page?: string;                 // 默认页面
  Default?: boolean;             // 是否默认应用
  Description?: string;          // 应用描述
}

UserInfo - 用户信息

interface UserInfo {
  readonly Id: string;           // 用户ID
  readonly Name: string;         // 用户名称
  readonly Code: string;         // 用户编码
  readonly TenantId: string | null; // 租户ID
  readonly UserLevel: string;    // 用户级别
  readonly Roles?: string[];     // 角色列表
  readonly Permissions?: string[]; // 权限列表
}

LoginInfo - 登录信息

interface LoginInfo {
  UserName: string;              // 用户名
  UserPass: string;              // 密码
  UserInfo?: UserInfo;           // 用户信息
  readonly token?: string;       // 访问令牌
  readonly refreshToken?: string; // 刷新令牌
}

枚举类型

AppSource - 应用来源

enum AppSource {
  Market = "Market",    // 从市场安装
  Manual = "Manual"     // 手动输入
}

AppAction - 应用动作

enum AppAction {
  App = "App",           // 应用模式加载
  MenuApp = "MenuApp",   // 托管应用模式加载
  Link = "Link",         // 链接方式打开
  Iframe = "Iframe"      // Iframe内嵌方式打开
}

通讯协议

请求格式

子应用发送到主应用的请求格式：

{
  type: 'API_REQUEST',
  id: number,        // 唯一请求ID，用于匹配响应
  method: string,    // 方法名称
  params?: any       // 请求参数（可选）
}

响应格式

主应用返回给子应用的响应格式：

{
  type: 'API_RESPONSE',
  id: number,        // 对应的请求ID
  success: boolean,  // 是否成功
  result?: any,      // 成功时的结果
  error?: string     // 失败时的错误信息
}

依赖要求

对等依赖 (Peer Dependencies)

• Vue: ^3.5.13 - Vue 3 框架
• Vue Router: ^4.5.0 - Vue 路由管理
• @skyfox2000/fapi: ^1.1.19 - API请求库
• @micro-zoe/micro-app: ^1.0.0-rc.18 - 微前端框架

构建配置

该库使用 Vite 进行构建，支持：

• TypeScript: 完整的类型支持
• ES Module: 现代化的模块格式
• 类型声明: 自动生成 .d.ts 文件
• 外部化依赖: 避免重复打包核心依赖

使用场景

1. 微前端子应用完整初始化

import { 
  isMicroApp, 
  initEnv, 
  initMicroBaseLog,
  initMainAppData,
  initMicroAppProxy,
  initModuleLoader,
  mainAppApis
} from '@skyfox2000/microbase';

// 1. 初始化环境变量
initEnv(import.meta.env);

// 2. 初始化日志（可选）
initMicroBaseLog(true);

// 3. 检测微应用环境并初始化通讯
if (isMicroApp()) {
  // 初始化主应用数据
  initMainAppData();
  
  // 初始化通讯层（数据监听 + 请求代理）
  initMicroAppProxy();
  
  // 初始化模块加载器
  initModuleLoader(import.meta.glob('./views/**/*.vue', { eager: false }));
}

// 4. 使用API
async function example() {
  const userInfo = await mainAppApis.getUserInfo();
  const appInfo = await mainAppApis.getAppInfo();
}

2. 独立应用

// 在独立应用中也可以使用类型定义
import type { AppInfo, UserInfo } from '@skyfox2000/microbase';

const appConfig: AppInfo = {
  Id: 'app-001',
  Name: '我的应用',
  AppCode: 'my-app',
  // ... 其他配置
};

版本历史

• v1.3.0: 统一通讯方式为 forceDispatch + addDataListener
• v1.2.1: 完善的微前端通信和类型定义
• v1.1.x: 增加模块加载功能
• v1.0.x: 初始版本，基础类型定义

注意事项

1. 依赖管理: 确保项目中已安装所有对等依赖
2. 环境检测: 在使用微前端功能前，先进行环境检测
3. 类型安全: 充分利用 TypeScript 类型检查，避免运行时错误
4. 版本兼容: 注意与其他 @skyfox2000 系列库的版本兼容性
5. 异步调用: 所有 mainAppApis 方法返回 Promise，需要使用 await 或 .then()

技术支持

• 仓库地址: GitHub - @skyfox2000/microbase
• 问题反馈: 通过 GitHub Issues 提交问题
• 文档更新: 随版本更新同步维护

该库是微前端生态系统的核心基础库，为构建大型企业级微前端应用提供坚实的技术基础。