基于 Vue 3 + Monorepo + 微前端的中后台前端项目框架全景解析

CassieHuu
1,449 阅读17分钟

本文档旨在全面、深入地剖析一个采用现代化技术栈构建的中后台前端项目。通过从宏观架构到微观代码实现，从理论分析到实践指南，完整地呈现该项目的设计思想、工程化实践与核心优势。

第一章：项目概览与技术选型

在深入架构细节之前，我们首先对项目的整体技术栈有一个清晰的认识。这是一个基于 Vue 3 生态，采用业界前沿工程化方案构建的复杂应用。

1.1. 整体技术栈概览

分类技术/库版本作用
核心框架Vue.js^3.5.22渐进式 JavaScript 框架
Vue Router^4.6.3官方路由管理器
构建工具Vite^5.4.20新一代前端构建工具
编程语言TypeScript~5.4.5JavaScript 的超集，提供静态类型
架构模式Qiankun^2.10.16微前端框架，用于构建大型复杂应用
状态管理Pinia^2.3.1Vue 官方推荐的状态管理库
UI 组件库Arco Design Vue^2.57.0字节跳动出品的企业级组件库
CSS 方案Tailwind CSS & Less^3.4.18 & ^4.4.2原子化 CSS 框架与 CSS 预处理器结合
HTTP 请求Axios^1.12.2基于 Promise 的 HTTP 客户端
代码规范ESLint, Prettier, Husky, commitlint-保证代码质量、风格统一和提交规范
开发工具Vue DevTools^7.7.7Vue 官方浏览器调试工具

第二章：核心架构设计思想

该项目成功的关键在于其先进的顶层架构设计，它通过 Monorepo 和微前端的组合拳，优雅地解决了大型项目的协作、扩展和维护难题。

2.1. 项目架构：基于 pnpm Workspaces 的 Monorepo + Qiankun 微前端

  • Monorepo: 该项目采用 pnpm 的 workspaces 功能来管理多个子应用（package）。 从 package.json 的 scripts 中可以看到，pnpm -F <package-name> dev 这样的命令用于独立启动不同的子应用。这种结构便于代码复用（如 common-ui, common-utils）、统一依赖管理和标准化工程配置。

  • 微前端 (Micro-Frontends): 项目引入了 qiankun 和 vite-plugin-qiankun。这表明项目采用微前端架构，其中有一个主应用（基座）负责承载和路由，而其他应用作为微应用被动态加载。qiankun 是一个基于 single-spa 的微前端实现方案，旨在轻松构建生产可用的微前端架构体系。 这种架构非常适合大型、由不同团队维护的复杂系统，可以实现独立开发、独立部署，降低了应用间的耦合度。

2.2. 系统关系图谱：基座、微应用与共享模块

为了更形象地理解各模块间的关系，我们可以将其想象成一个“太阳系”：

  • 🪐 太阳 (基座应用): dvp-portal
  • orbiting_planet 行星 (微应用): * dvp-backstage * dvp-blue-shield * dvp-business-hub * dvp-ar-benefit * dvp-procure-guard * dvp-legal-monitor
  • 🌌 宇宙法则 (共享模块):
    • common-ui
    • common-utils

详细关系解读:

  1. dvp-portal (基座应用 - The Main App/Portal) dvp-portal 是整个系统的核心入口和容器。

    • 角色: 它是 Qiankun 架构中的 主应用（基座）。
    • 职责:
      • 应用框架提供者: 提供整个应用的“外壳”，包括顶部导航栏、侧边菜单栏、用户状态管理等全局 UI 元素。
      • 路由中心: 负责监听浏览器 URL 变化，动态加载并渲染对应的微应用。
      • 全局状态与通信: 管理全局共享的状态（如用户信息），并提供应用间的通信机制。
      • 用户认证: 统一处理登录逻辑，并将认证信息传递给各个微应用。

  2. 其他 dvp-* 应用 (微应用 - The Micro Apps) dvp-backstage, dvp-blue-shield 等都是独立的、功能内聚的 微应用。

    • 角色: 它们是 Qiankun 架构中的 子应用。
    • 职责:
      • 业务功能实现: 专注于实现特定的业务功能。
      • 独立开发与部署: 可由不同团队独立开发、测试和部署，不影响其他应用。
      • 与基座的关系: 遵循 Qiankun 协议，导出生命周期钩子，由基座进行加载和卸载。

  3. common-ui & common-utils (共享模块 - The Shared Libraries) 这两个包是整个 Monorepo 的基石，体现了代码复用的最佳实践。

    • 角色: 被所有应用共享的本地依赖包。
    • common-ui 的职责: 封装通用业务组件，确保所有系统 UI 一致性。
    • common-utils 的职责: 提供跨应用的通用工具函数，如封装的 axios 实例、日期格式化、权限验证等。

2.3. 构建与开发环境：Vite 生态系统

项目全面拥抱 Vite 生态，以提升开发体验和构建效率。

  • Vite 作为构建核心: 利用其基于原生 ES Module 的开发服务器，提供了极快的冷启动和热更新（HMR）速度。
  • 基础配置 (vite.base.config.ts): 抽象通用 Vite 配置，包括路径别名、构建产物分类、生产环境移除 console.log 等优化。
  • 子应用配置: 通过 unplugin-auto-import 和 unplugin-vue-components 实现组件和 API 的按需加载；通过 server.proxy 解决开发环境跨域问题；通过 base 配置项支持微前端部署。

2.4. 代码质量与工程化

项目建立了一套完整的工程化体系来保障代码质量和开发效率：

  • TypeScript: 全面采用，提供静态类型检查，增强代码的可维护性和健壮性。
  • ESLint & Prettier: 结合使用，统一代码风格和编码规范。
  • Husky & commitlint: 通过 Git Hooks，在代码提交前自动运行 commitlint 检查提交信息是否符合规范，确保提交历史的清晰可读。

第三章：核心流程深度剖析

理解了宏观架构后，我们通过分析两个最关键的用户流程——统一登录和路由系统，来深入探究该架构在实践中是如何运作的。

3.1. 架构剖析：以“统一登录”模块为核心

统一登录是串联起所有系统的“钥匙”。其实现方式清晰地反映了整个项目的架构思想。

统一登录流程分析：

  1. 用户访问入口: 任何访问都首先由 dvp-portal (基座应用) 接管。
  2. 认证检查 (在基座中): 基座的路由守卫会检查本地 Token。若无效，则重定向到基座的登录页；若有效，则继续。
  3. 用户登录: 用户在基座登录页完成认证，基座将获取的 Token 存入 Cookie，并将用户信息存入 Pinia。
  4. 加载微应用: 登录成功后，Qiankun 根据 URL 加载对应的微应用。
  5. 认证信息同步: 微应用通过 common-utils 中封装的全局 axios 实例发起请求。该实例的请求拦截器会自动从 Cookie 中读取 Token 并添加到请求头中。

    关键实践: 所有应用都 不直接使用 axios，而是使用这个来自共享模块的预配置实例，从而实现认证能力的无感植入。

  6. 登出: 用户点击基座上的“登出”按钮，由基座负责清除 Token 和全局状态，并重定向回登录页。

架构优势总结：

  • 职责单一: 基座全权负责认证、路由分发和全局布局。
  • 关注点分离: 微应用无需关心登录逻辑，只需专注于自身业务。
  • 高内聚、低耦合: 认证逻辑内聚在基座中，与微应用解耦。
  • 体验无缝: 对用户而言，整个系统浑然一体，体验流畅。

3.2. 架构剖析：以“路由系统”为核心

项目的路由系统被巧妙地拆分成了两层：基座主路由 + 微应用子路由。

路由工作流程详解：

我们可以将这个关系想象成一个大型机场的运作模式：

  • ✈️ 机场塔台 (基座主路由): 决定了用户请求应该飞往哪个微应用。
  • 팻 航站楼内部指引 (微应用子路由): 一旦进入微应用，其内部路由负责引导用户到具体的业务页面。

  1. 入口与分发 (在 dvp-portal 中): 当用户访问 https://.../backstage/users 时，基座的 vue-router 首先捕获请求。它的路由表中配置了通配规则，如 { path: '/backstage/:pathMatch(.*)*', ... }。当匹配成功，基座便通知 Qiankun 去加载 dvp-backstage 应用。

  2. 微应用接管 (在 dvp-backstage 中): dvp-backstage 内部拥有自己独立的 vue-router 实例，并配置了 history: createWebHistory('/backstage/')。它会接管 URL 中 /backstage/ 之后的部分（即 /users），并将其匹配到自己的业务页面组件。

架构优势分析：

  • 高度解耦: 每个微应用管理自己的路由，互不干扰。
  • 职责清晰: 基座只做“分发”，业务应用只做“实现”。
  • 独立部署与迭代: 路由变更可以跟随微应用独立上线，提升交付效率。
  • 无缝的用户体验: URL 变化和页面切换对用户来说是平滑无感的。

3.3. 实践揭秘：dvp-portal 中动态路由与权限控制的代码实现

前文概述了分层路由的宏观策略，本节将深入 dvp-portal 的路由代码，揭示这套基于后端权限、动态生成路由的最佳实践是如何将认证、权限、路由和菜单系统精巧地串联起来的。

整体设计思想：

该路由系统的核心思想是：

  • 静态路由 + 动态路由：系统包含一小部分用于承载基础布局和公共页面的静态路由（如登录页），以及大部分业务动态路由。
  • 权限驱动：动态路由并非硬编码在前端，而是由用户登录后从后端 API (getPermissionTree) 获取的权限树动态生成。
  • 一次性生成：在用户登录后的首次导航时，一次性获取权限、生成所有可访问的路由并添加到 vue-router 实例中，同时将菜单数据存入 Pinia (commonStore) 以供渲染。

代码逐段分析：

1. 初始化与平台判断

import { pcRoutes, mobileRoutes } from './routes';

const isMobile = terminalJudgment(),
  router = createRouter({
    history: createWebHistory(import.meta.env.BASE_URL),
    routes: isMobile ? mobileRoutes : pcRoutes
  });
  • 分析: 代码首先通过 terminalJudgment() 判断当前是移动端还是 PC 端。根据判断结果，加载不同的初始静态路由表 (mobileRoutes 或 pcRoutes)。这表明项目对不同终端有独立的布局和基础页面，设计考虑周全。

2. 动态组件加载与路由处理函数

const modulesFile = import.meta.glob(['@/modules/**/*.vue', '!**/{login,mobile,poc,portal,workbench}']),
  processSystemRoute = (tree?: PermissionTreeType, module?: string | symbol) => {
    const result: RouteRecordRaw[] = [];
    tree?.forEach((item) => {
      if (!item.metaData) return;
      const { component = '', name } = item.metaData,
        newItem = {
          ...item.metaData,
          children: processSystemRoute(item.childrens, module || name)
        };
      newItem.component = modulesFile[`/src/modules/${String(module || name)}/${component}`];
      result.push(newItem);
    });
    return result;
  };
  • import.meta.glob: 这是 Vite 提供的一个非常强大的功能。它会扫描 @/modules/ 目录下所有的 .vue 文件，并创建一个映射表 (modulesFile)。这使得后续可以根据一个字符串路径动态地、异步地加载对应的 Vue 组件，而无需手动 import 每一个组件。
  • processSystemRoute (核心函数):
    • 这是一个递归函数，负责将后端返回的树形权限数据 (PermissionTreeType) 转换成 vue-router 可识别的路由记录数组 (RouteRecordRaw[])。
    • 关键逻辑: newItem.component = modulesFile[...]。它根据后端返回的 component 字符串（如 'UserManagement.vue') 和模块名 (name)，拼接出一个文件路径，然后从 modulesFile 映射表中查找到对应的组件加载函数。这就是实现路由组件动态绑定的魔法所在。
    • 这种设计将前端路由与后端权限完美解耦。后端只需要通过 JSON 数据告诉前端“这个菜单叫什么，路径是什么，对应哪个组件文件”，前端就能自动完成路由的创建。

3. 全局导航守卫 (router.beforeEach) 这是整个路由系统的“大脑”，控制着所有的导航行为。

router.beforeEach(async (to, from) => {
  const { path, query, meta } = to,
    token = getToken(),
    commonStore = useCommonStore();
  // ...

  • 白名单与登录逻辑: 首先处理了已登录用户访问登录页、白名单路径、未登录用户访问受保护页面等标准认证流程。如果没有 token，则通过 redirectLogin() 跳转到登录页。

  • 动态路由生成逻辑 (最关键的部分):

    if (!commonStore.systemMenus) {
  commonStore.systemMenus = [];
  const res = await getPermissionTree();
  processSystemRoute(res).forEach((item) => {
    router.addRoute(item);
    commonStore.systemMenus?.push(item);
  });
  return { ...to, replace: true };
}
    • 触发条件: !commonStore.systemMenus。这个条件判断用户已登录（有 token），但 Pinia store 中还没有系统菜单数据。这通常只在用户登录后的第一次页面跳转时发生。
    • 防止重复: commonStore.systemMenus = [] 立即设置一个空数组，防止因为异步操作导致此代码块被重复执行。
    • 获取与处理: await getPermissionTree() 从后端获取权限树，然后通过 processSystemRoute(res) 将其转换为路由记录。
    • 注入路由: router.addRoute(item) 将新生成的路由一条条地动态添加到 vue-router 实例中。
    • 存储菜单: commonStore.systemMenus?.push(item) 将路由数据也存入 Pinia，提供给菜单组件（如侧边栏）进行渲染。
    • 重新导航: return { ...to, replace: true } 是点睛之笔。当 addRoute 执行完毕后，当前的导航需要被中断并重新发起一次。replace: true 确保这次重定向不会留下历史记录。当导航重新开始时，vue-router 已经拥有了新的路由表，因此可以正确匹配到用户想要访问的目标页面。

第四章：开发与部署策略

优秀的架构不仅要设计优雅，还必须能支持高效的开发和灵活的部署。

4.1. 本地开发管理：pnpm workspace 的符号链接机制

在本地开发中，pnpm 通过 符号链接（Symbolic Link） 机制提供了极致的开发体验。

  • 原理: 您可以将符号链接想象成电脑桌面上的快捷方式。当 dvp-portal 依赖 common-utils 时，pnpm 不会复制一份代码，而是在 dvp-portal/node_modules/ 里创建一个指向 packages/common-utils 真实位置的“快捷方式”。
  • 带来的好处:
    1. 实时更新: 当您修改了 common-utils 包中的代码，所有依赖它的本地应用会立即感知到变化。结合 Vite 的热更新 (HMR)，您可以实时看到修改效果，无需任何重新构建或安装。
    2. 单一代码源: 保证了整个项目中共享包只有一个版本和一份代码，避免了依赖地狱。
    3. 简化调试: 可以直接从应用代码无缝跳转到共享包的源码进行调试。

4.2. 自由组合与本地化交付部署

这个 “一个基座 + 多个可插拔的微应用” 的设计模式，非常适合进行自由组合和本地化交付部署。

运作方式：

假设客户只需要后台管理 (dvp-backstage) 和业务中心 (dvp-business-hub) 两个功能。

  1. 打包构建: 只需分别构建 dvp-portal、dvp-backstage 和 dvp-business-hub。其他微应用则完全忽略。
  2. 服务器部署: 将基座和所需的微应用产物部署到服务器的不同路径下。
  3. 动态加载配置: 在基座中，通过一份配置文件来注册需要加载的微应用。这份配置只包含 dvp-backstage 和 dvp-business-hub，这样用户的菜单中就只会显示这两个系统的入口。

架构优势总结：

  • 灵活性极高: 可以像“搭积木”一样为不同客户定制产品组合。
  • 部署包最小化: 只部署客户需要的功能模块，减少资源占用。
  • 维护和升级独立: 可对单个微应用进行热更新和敏捷交付，不影响其他系统。

第五章：代码级设计模式范例

在代码层面，项目巧妙地运用了多种设计模式来保证代码的健壮性和可维护性。

5.1. 单一实例（Singleton-like）模式范例

指那些在整个应用生命周期中，其逻辑和状态是全局唯一的、共享的模块。

  • 通用认证 Token 获取 (getGeneralToken): 从一个硬编码的 Cookie 键中读取数据，提供全局唯一的、标准的 Token 获取方式。
  • 文件下载工具 (downloadFile): 纯粹的、无状态的工具函数，在整个项目中提供单一、可复用的功能实现。
  • 身份证验证工具 (idCardVerify): 典型的无状态验证函数，内部逻辑固定，在任何模块调用都得到相同的验证行为。
  • HTTP 状态码映射 (errorCodeMap): 一个导出的常量对象，为整个项目提供了一套统一的 HTTP 错误码映射，是唯一的“真理之源”。

5.2. 多实例（Multi-instance）模式范例

通常通过类或工厂函数实现，每次创建实例时，都可以传入不同配置，使得每个实例拥有自己独立的状态和行为。

  • HttpService 网络请求服务: 最典型的多实例范例。通过 new HttpService(...) 创建实例，每个实例可以接收不同的 baseURL、logoutFn 等配置，从而拥有指向不同后端、包含独立拦截器的 axios 实例。
  • 各个子应用的认证逻辑 (auth.ts): 每个子应用都拥有自己的 auth.ts，它们使用不同的 TokenKey（如 'Token', 'token-dams'）。这本质上是多实例模式的应用，隔离了不同业务系统的认证体系，避免 Token 互相覆盖。
  • Vite 基础配置工厂 (createBaseConfig): 一个工厂函数，接收参数并为每个子应用生成一个定制化的 Vite 配置实例（例如，@ 别名指向各自的 src 目录）。
  • Vite 依赖预构建产物: Vite 为每个应用创建了独立的依赖预构建文件夹 (.vite/deps)，确保了每个应用的依赖环境是隔离的。

第六章：从理论到实践：实现指南

理解了上述理论后，本章将提供一些关键的“战术层面”实现细节，帮助您从零到一构建类似的项目。

6.1. 如何配置 Qiankun 基座和微应用？

在 dvp-portal (基座) 中： 你需要一个入口文件来注册微应用。

// src/micro-app.ts (示例)
import { registerMicroApps, start } from 'qiankun';

// 1. 定义微应用列表
const apps = [
  {
    name: 'dvp-backstage', // 唯一名称
    entry: import.meta.env.DEV ? '//localhost:3001' : '/backstage/', // 微应用的访问地址
    container: '#subapp-container', // 挂载容器的 CSS 选择器
    activeRule: '/backstage', // 激活规则，URL 匹配时加载
  },
  // ... 其他微应用
];

// 2. 注册并启动
registerMicroApps(apps);
start({
  prefetch: 'all', // 预加载所有微应用资源
  sandbox: { strictStyleIsolation: true } // 开启严格的样式隔离
});

同时，在你的主布局组件中，必须包含 <div id="subapp-container"></div> 作为挂载点。

在 dvp-backstage (微应用) 中： 你需要 vite-plugin-qiankun 来帮助你导出生命周期。

// vite.config.ts
import qiankun from 'vite-plugin-qiankun';

export default defineConfig({
  plugins: [
    qiankun('dvp-backstage', { // 'dvp-backstage' 必须和基座注册的 name 一致
      useDevMode: true
    })
  ],
});

// src/main.ts
import { renderWithQiankun, qiankunWindow } from 'vite-plugin-qiankun/dist/helper';

let app: App;

function render(props: any) {
  const { container } = props;
  app = createApp(RootComponent);
  app.mount(container ? container.querySelector('#app') : '#app');
}

if (!qiankunWindow.__POWERED_BY_QIANKUN__) {
  render({}); // 独立运行
} else {
  // 导出 Qiankun 需要的生命周期钩子
  renderWithQiankun({
    mount(props) { render(props); },
    bootstrap() { /* ... */ },
    unmount(props) { app.unmount(); },
  });
}

6.2. 如何实现动态菜单和路由？

项目的权限和菜单是由后端 API 动态生成的。

在 dvp-portal (基座) 中：

  1. 登录后获取权限: 调用 API 获取权限和菜单的 JSON 数据。
  2. 解析数据: 编写一个函数递归遍历这份数据。
    • 生成路由: 将数据转换成 vue-router 的路由记录。对于微应用的路由，生成通配规则，如 { path: '/backstage/:pathMatch(.*)*', ... }。使用 router.addRoute() 动态添加。
    • 生成菜单: 将数据转换成 UI 组件库（如 Arco Design）的 menu 组件所需的数据结构，用于渲染侧边栏。
    • 注册微应用: 从数据中提取出微应用信息，动态生成 registerMicroApps 所需的 apps 列表。

6.3. 如何优雅地处理多实例配置？

  • HttpService: 每个应用在自己的入口处 new HttpService(...)，传入各自的 baseURL 和特定的 getToken 函数。这样，每个应用就拥有了指向不同后端、使用不同 Token 逻辑的独立请求实例。
  • auth.ts: 每个应用内部都有一个 auth.ts，它们使用不同的 TokenKey。这是为了隔离不同业务系统的认证体系，是一个非常周全的考虑，特别是在本地化交付时，不同系统可能对接不同的认证中心。

第七章：总结

总的来说，这个项目采用了一套非常成熟且主流的技术方案。

  • 架构先进: Monorepo + 微前端的组合拳，很好地解决了大型前端项目的管理和协作痛点。
  • 工具链现代: 全面拥抱 Vite 生态，开发体验和构建效率都处于业界前沿。
  • 工程化完备: 从代码规范、提交规范到自动化检查，形成了一套完整的质量保障体系。
  • 技术选型合理: Vue 3 + Pinia + TypeScript + Arco Design 是目前构建中后台应用的黄金组合之一。

通过以上全面的分析，我们不仅理解了该项目的设计思想，也掌握了从零开始构建一个类似的高质量前端项目的关键知识和实践方法。项目的关键知识和实践方法。

avatar
文章
阅读
粉丝