构建可持续交付的SaaS平台(8)——谷雨SaaS前端架构：从矮化到核心的蜕变

在企业级 SaaS 平台开发中，前端往往陷入 “矮化” 困境：没有独立身份、强依赖后端接口、业务边界模糊，最终沦为 “页面绘制工具”，迭代效率低下且难以适配多租户的个性化需求。

作为以 “应用化” 为核心的开源 SaaS 平台，谷雨（G2rain）的前端架构设计从根源上解决了这个问题 —— 通过 分层架构+微前端+独立安全能力 的组合拳，让前端拥有了独立身份、清晰边界和全生命周期管理能力。今天就带大家深度拆解 g2rain-main-shell 的前端架构设计，看看它是如何让前端从 “辅助角色” 升级为 “核心载体” 的。

一、架构设计的核心目标：让前端不再 “依附” 后端

在设计 g2rain-main-shell 时，我们确立了三个核心目标，直接对标前端 “矮化” 的三大痛点：

最终实现的价值很明确：前端能独立对接客户需求，负责业务逻辑、身份认证、跨应用通信；后端专注于架构稳定性和接口能力，真正实现 “各司其职、高效协作”。

二、分层架构：5 层设计，让每一层都 “可复用、可替换”

g2rain-main-shell 的核心亮点之一是清晰的分层架构，从下到上依次为「共享层→平台层→运行时层→壳层→业务层」，每层职责单一、依赖明确，既保证了复用性，又提升了扩展性。

🏗️ 分层全景图（从核心到表象）

plaintext

┌───────────── 业务层 views ─────────────┐ # 具体业务模块（如个人信息编辑，密码修改）
├────────────── 壳层 shell ──────────────┤ # 主应用UI框架（布局、组件、路由映射）
├──────────── 运行时层 runtime ──────────┤ # 核心服务（认证、HTTP、微前端启动）
├──────────── 平台层 platform ───────────┤ # 可复用能力（微前端管理、状态、主题）
└──────────── 共享层 shared ─────────────┘ # 通用工具（JWT、UUID生成器）

各层核心职责与设计亮点

1. 共享层（shared）：通用能力的 “工具箱”

• 核心内容：仅包含跨模块复用的工具函数（如 JWT 解析、UUID 生成、DPoP 签名工具）
• 设计原则：无状态、无依赖，主应用和子应用可直接引用，不涉及任何业务逻辑
• 关键文件：jwt.util.ts（封装密钥生成、Token 验证）、generator.ts（通用生成器）

2. 平台层（platform）：可复用的 “基础能力底座”

这一层是整个架构的核心，提供所有应用（主应用 + 子应用）都能使用的基础能力，核心亮点是抽象化 + 适配器模式。

• 核心模块：

• • 微前端管理器（platform/apps）：定义BaseAppManager抽象接口，通过QiankunAdapter适配 qiankun 框架，未来替换为其他微前端框架（如 Module Federation）只需新增适配器，无需修改核心代码；
  • 状态管理（platform/stores）：Pinia 集中管理状态，遵循「单一数据源」原则（App 定义→app.store、运行时实例→runtime.store、Tab→tab.store），避免状态冗余；
  • 主题系统（platform/theme）：支持亮色 / 暗色 / 品牌主题切换，通过 CSS 变量 +data-theme属性实现运行时切换，且自动持久化到本地存储。

3. 运行时层（runtime）：服务生命周期的 “总指挥”

负责所有核心服务的启动、运行、卸载，确保服务按依赖顺序加载，核心亮点是生命周期统一管理。

• 核心模块：

• • 认证服务（runtime/auth）：封装 SSO 单点登录流程，包括跳转、Token 生成、刷新，与 DPoP 签名服务联动；
  • HTTP 客户端（runtime/http）：统一 Axios 配置，支持 Mock、Token 自动注入、错误统一处理，还能通过请求头x-g2rain-mock强制触发 Mock；
  • 启动器（runtime/boot）：按依赖顺序启动服务（SSO→资源加载→微应用注册→Tab 路由同步），卸载时反向清理，避免内存泄漏。

4. 壳层（shell）：主应用的 “UI 框架”

仅负责主应用的布局和基础 UI，不包含业务逻辑，核心亮点是布局与业务分离。

• 核心模块：

• • 布局组件（shell/layout）：MainLayout包含 Header、Sidebar、TabBar、Footer，其中TabBar是微应用实例管理的 “入口”；
  • 路由映射（shell/route-map.ts）：定义壳层路由（如/映射到工作台Workspace.vue），与业务路由分离，便于维护。

5. 业务层（views）：具体业务的 “实现载体”

包含认证、用户、角色等具体业务模块，核心亮点是业务与框架解耦—— 业务代码仅依赖平台层和运行时层的能力，无需关心微前端、布局等底层实现。

三、微前端设计：适配器 + Tab 驱动，解决 “多实例冲突” 痛点

SaaS 平台需要支持多应用同时运行（如同一客户打开多个子应用 Tab）。为此，我们设计了「适配器模式 + Tab 驱动实例管理」的解决方案。通过抽象微前端模块层，提供了切换不同的微前端组件的能力。

🚀 微前端核心架构

plaintext

┌───────────── TabBar.vue（触发者） ──────────────┐
├───────────── runtime.store（实例管理者） ────────┤
├───────────── BaseAppManager（抽象接口） ─────────┤
└───────────── QiankunAdapter（具体实现） ─────────┘

关键设计：Tab 与实例 “一一对应”

每个子应用 Tab 对应一个RuntimeInstance（实例 ID=TabKey），实例的生命周期完全由 Tab 状态驱动：

适配器模式的价值

通过BaseAppManager抽象接口定义微应用管理的通用方法（mount/unmount/destroy），QiankunAdapter实现 qiankun 专属逻辑。未来如果要替换微前端框架，只需新增一个适配器（如ModuleFedAdapter），无需修改 Tab 驱动、实例管理等核心逻辑，扩展性拉满。

四、架构核心价值：3 个维度提升 SaaS 平台竞争力

五、总结：前端架构的 “破局关键”

谷雨 g2rain-main-shell 的前端架构，本质是通过「分层解耦」赋予前端独立能力，通过「微前端 + Tab 驱动」解决多应用协同问题，通过「适配器 + 单一数据源」保证扩展性和稳定性。

它打破了 SaaS 平台前端 “矮化” 的困局，让前端从 “页面绘制工具” 升级为 “业务承载载体”—— 前端团队可直接对接客户需求，后端团队专注架构建设，这种协作模式为 SaaS 平台的规模化发展奠定了基础。