Modern.js 微前端开发指南：useModuleApps API 详解

概述

在现代前端开发中，微前端架构已经成为解决大型应用复杂性的重要方案。Modern.js 框架提供了强大的微前端支持，其中 useModuleApps 是一个核心 API，它能够帮助开发者灵活地管理和加载微前端子应用。

useModuleApps 核心功能

useModuleApps 是 Modern.js 微前端插件提供的一个 React Hook，它主要实现以下功能：

1. 返回所有已注册微前端子应用的 React 组件
2. 支持两种路由控制模式：自控式路由和集中式路由
3. 提供子应用加载状态管理能力
4. 允许自定义加载过渡效果

基本使用方法

安装与引入

首先确保项目中已经安装了 Modern.js 的微前端插件，然后可以这样引入：

import { useModuleApps } from '@modern-js/plugin-garfish/runtime';

基础配置

在使用前，需要在项目配置中定义微前端子应用信息：

defineConfig(App, {
  masterApp: {
    apps: [
      {
        name: 'Table',
        entry: 'http://127.0.0.1:8081/',
      },
      {
        name: 'Dashboard',
        entry: 'http://localhost:8082',
      },
    ],
  },
});

两种路由模式详解

1. 自控式路由模式

自控式路由模式下，开发者需要手动定义路由规则，适合需要在前置路由中添加额外逻辑（如权限校验）的场景。

function App() {
  const { apps, MApp, Table, Dashboard } = useModuleApps();

  const router = createBrowserRouter(
    createRoutesFromElements(
      <Route path="/" element={<AppLayout />}>
        <Route path="table/*" element={<Table />} />
        <Route path="dashboard/*" element={<Dashboard />} />
      </Route>
    )
  );

  return <RouterProvider router={router} />;
}

2. 集中式路由模式

集中式路由模式下，路由规则在配置中定义，适合简单的路由匹配场景。

defineConfig(App, {
  masterApp: {
    apps: [
      {
        name: 'Table',
        activeWhen: '/table',
        entry: 'http://127.0.0.1:8081/',
      },
      {
        name: 'Dashboard',
        activeWhen: '/dashboard',
        entry: 'http://localhost:8082',
      },
    ],
  },
});

使用时只需渲染 MApp 组件：

function App() {
  const { MApp } = useModuleApps();
  return <MApp />;
}

高级功能

自定义加载动画

useModuleApps 返回的子应用组件支持 loadable 属性，可以用来自定义加载状态：

<Component
  loadable={{
    loading: ({ pastDelay, error }) => {
      if (error) {
        return <div>加载出错: {error?.message}</div>;
      } else if (pastDelay) {
        return <div>加载中...</div>;
      }
      return null;
    },
  }}
/>

动态获取子应用列表

useModuleApps 返回的 apps 数组包含了所有注册的子应用信息，可以动态渲染：

apps.map(app => (
  <Route
    key={app.name}
    path={`${app.name.toLowerCase()}/*`}
    element={<app.Component />}
  />
))

最佳实践建议

1. 命名规范：子应用名称区分大小写，建议采用一致的命名规范
2. 路由设计：自控式路由适合复杂场景，集中式路由适合简单场景
3. 错误处理：始终实现加载错误状态处理
4. 性能优化：考虑为子应用添加加载延迟显示，避免闪烁
5. 开发环境：确保子应用的开发服务器支持跨域访问

常见问题解答

Q: 子应用组件名称与配置不一致怎么办？

A: useModuleApps 返回的组件名称严格匹配配置中的 name 字段，注意大小写敏感。

Q: 如何实现子应用预加载？

A: 可以通过提前渲染子应用组件但不显示的方式实现预加载，或使用微前端框架提供的预加载API。

Q: 子应用加载失败如何处理？

A: 通过 loadable 属性的 loading 回调可以捕获错误并显示友好提示。

通过掌握 useModuleApps API，开发者可以在 Modern.js 框架下轻松构建灵活、高效的微前端架构应用。