audio/dashboard
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3a0108dc545aec919b3dc8358cd8c7eb4f6277b3
dashboard/.qoder/repowiki/zh/content/系统架构/前端架构.md
T
eafonyang d292c23dc0 更新 wiki
2026-07-17 17:17:22 +08:00

18 KiB
Raw Blame History

前端架构

**本文引用的文件** - [frontend/package.json](file://frontend/package.json) - [frontend/vite.config.ts](file://frontend/vite.config.ts) - [frontend/src/main.ts](file://frontend/src/main.ts) - [frontend/src/App.vue](file://frontend/src/App.vue) - [frontend/src/router/index.ts](file://frontend/src/router/index.ts) - [frontend/src/layouts/base-layout/index.vue](file://frontend/src/layouts/base-layout/index.vue) - [frontend/src/service/api/index.ts](file://frontend/src/service/api/index.ts) - [frontend/src/service/request/index.ts](file://frontend/src/service/request/index.ts) - [frontend/src/store/index.ts](file://frontend/src/store/index.ts) - [frontend/src/hooks/common/router.ts](file://frontend/src/hooks/common/router.ts) - [frontend/packages/alova/package.json](file://frontend/packages/alova/package.json) - [frontend/packages/axios/package.json](file://frontend/packages/axios/package.json) - [frontend/packages/color/package.json](file://frontend/packages/color/package.json) - [frontend/packages/hooks/package.json](file://frontend/packages/hooks/package.json) - [frontend/packages/materials/package.json](file://frontend/packages/materials/package.json) - [frontend/packages/scripts/package.json](file://frontend/packages/scripts/package.json) - [frontend/packages/uno-preset/package.json](file://frontend/packages/uno-preset/package.json) - [frontend/packages/utils/package.json](file://frontend/packages/utils/package.json)

更新摘要

所做更改

  • 完全重写前端架构，从旧的Vue 2实现迁移到新的Soybean Admin框架
  • 引入monorepo结构，包含8个核心包：alova、axios、color、hooks、materials、scripts、uno-preset、utils
  • 采用现代化的组件组织方式和开发工作流
  • 更新状态管理策略，使用Pinia替代Vuex
  • 重构HTTP客户端层，集成Alova和Axios双方案
  • 增强TypeScript类型支持和开发体验

目录

  1. 引言
  2. 项目结构
  3. Monorepo架构
  4. 核心架构设计
  5. 组件体系
  6. 状态管理
  7. API请求层
  8. 路由与导航
  9. 主题与样式系统
  10. 构建与部署
  11. 性能优化
  12. 开发工作流
  13. 故障排查指南
  14. 结论

引言

本文件详细阐述全新重构的基于Soybean Admin的前端架构设计与实现。该架构采用现代化的monorepo结构，集成了Alova HTTP客户端、UnoCSS原子化样式、Pinia状态管理等先进技术栈。重点覆盖Composition API最佳实践、TypeScript类型安全、组件层次结构、路由配置与鉴权策略、状态管理、构建优化、前后端交互模式以及完整的开发工作流。

项目结构

新架构采用清晰的monorepo组织结构，主应用位于frontend目录，核心功能模块以packages形式独立管理：

graph TB
subgraph "主应用 frontend"
A["src/<br/>源代码"] --> B["components/<br/>业务组件"]
A --> C["layouts/<br/>布局组件"]
A --> D["service/<br/>API服务层"]
A --> E["store/<br/>状态管理"]
A --> F["router/<br/>路由配置"]
A --> G["hooks/<br/>组合式函数"]
A --> H["theme/<br/>主题配置"]
A --> I["plugins/<br/>插件注册"]
end
subgraph "核心包 packages"
J["alova/<br/>HTTP客户端"]
K["axios/<br/>HTTP客户端"]
L["color/<br/>颜色工具"]
M["hooks/<br/>通用Hooks"]
N["materials/<br/>UI材料库"]
O["scripts/<br/>构建脚本"]
P["uno-preset/<br/>样式预设"]
Q["utils/<br/>工具函数"]
end
A -.-> J
A -.-> K
A -.-> L
A -.-> M
A -.-> N
A -.-> O
A -.-> P
A -.-> Q

图表来源

章节来源

Monorepo架构

新架构采用pnpm workspace管理的monorepo结构，将可复用的功能模块拆分为独立的package：

核心包说明

  • alova: 基于Alova的现代化HTTP客户端封装，支持缓存、拦截器、类型推断
  • axios: 传统Axios客户端封装，提供向后兼容的API接口
  • color: 颜色处理工具库，支持主题色计算、格式转换
  • hooks: 通用组合式函数库，包含路由、表单、表格等常用逻辑
  • materials: UI组件材料库，提供基础组件和业务组件
  • scripts: 构建和部署脚本，自动化开发流程
  • uno-preset: UnoCSS预设配置，统一样式规范
  • utils: 通用工具函数库，包含日期、验证、存储等工具

包依赖关系

graph LR
main["主应用"] --> alova["alova包"]
main --> axios["axios包"]
main --> hooks["hooks包"]
main --> materials["materials包"]
alova --> utils["utils包"]
axios --> utils
hooks --> utils
materials --> color["color包"]
materials --> uno-preset["uno-preset包"]
scripts["scripts包"] --> main

图表来源

章节来源

核心架构设计

新架构采用分层设计原则，清晰分离关注点，提升代码可维护性和可测试性：

架构分层

  • 表现层 (Presentation Layer): Vue组件、布局、页面视图
  • 业务逻辑层 (Business Logic Layer): 组合式函数、业务Hooks
  • 数据访问层 (Data Access Layer): API服务、状态管理
  • 基础设施层 (Infrastructure Layer): HTTP客户端、工具函数、第三方库封装

技术栈概览

  • 框架: Vue 3 + Composition API + TypeScript
  • UI库: Naive UI + 自定义组件
  • 样式: UnoCSS + SCSS + CSS变量
  • 状态管理: Pinia + localStorage持久化
  • HTTP客户端: Alova (推荐) + Axios (兼容)
  • 路由: Vue Router 4 + 动态路由
  • 构建工具: Vite 5 + pnpm workspace
  • 代码质量: ESLint + Prettier + TypeScript严格模式

章节来源

组件体系

新架构采用三层组件分类体系，确保组件的可复用性和可维护性：

组件分类

  • 基础组件 (Base Components): 无业务逻辑的纯展示组件
  • 业务组件 (Business Components): 封装特定业务逻辑的组件
  • 页面组件 (Page Components): 页面级别的容器组件

组件组织原则

  • 按功能域组织，而非按技术类型
  • 每个组件职责单一，遵循单一职责原则
  • 使用TypeScript定义严格的props和emits类型
  • 优先使用Composition API编写逻辑
graph TD
A["页面组件<br/>Page Components"] --> B["业务组件<br/>Business Components"]
B --> C["基础组件<br/>Base Components"]
A --> D["布局组件<br/>Layout Components"]
D --> E["通用组件<br/>Common Components"]
E --> F["UI组件<br/>UI Components"]

图表来源

章节来源

状态管理

新架构采用Pinia进行状态管理，结合TypeScript提供完整的类型支持：

Store结构设计

  • app store: 应用全局状态（语言、主题、侧边栏状态）
  • auth store: 用户认证状态（令牌、用户信息、权限）
  • route store: 路由相关状态（动态路由、面包屑）
  • tab store: 标签页状态（打开的标签、活动标签）
  • theme store: 主题配置状态（主题色、布局模式）

状态持久化

  • 使用localStorage持久化关键状态
  • 自动序列化/反序列化处理复杂对象
  • 支持状态版本管理和迁移
sequenceDiagram
participant C as 组件
participant S as Pinia Store
participant L as localStorage
participant API as 后端API
C->>S : 调用action
S->>API : 发起网络请求
API-->>S : 返回数据
S->>S : 更新状态
S->>L : 持久化状态
S-->>C : 响应更新
C->>C : 重新渲染

图表来源

章节来源

API请求层

新架构提供双HTTP客户端方案，支持Alova和Axios两种选择：

Alova方案（推荐）

  • 基于Alova的现代化HTTP客户端
  • 内置请求缓存、重试机制
  • 完整的TypeScript类型推断
  • 支持Mock数据和单元测试

Axios方案（兼容）

  • 传统Axios封装，保持向后兼容
  • 统一的错误处理和拦截器
  • 请求取消和超时控制

请求拦截器链

flowchart LR
A["请求发起"] --> B["请求拦截器"]
B --> C["认证令牌注入"]
C --> D["请求日志记录"]
D --> E["发送请求"]
E --> F["响应拦截器"]
F --> G["错误处理"]
G --> H["数据转换"]
H --> I["返回结果"]

图表来源

章节来源

路由与导航

新架构采用Vue Router 4，支持动态路由、路由守卫和懒加载：

路由配置

  • 静态路由：登录页、404页面等固定路由
  • 动态路由：根据用户权限动态生成菜单和路由
  • 路由元信息：权限控制、面包屑、标题等配置

路由守卫

  • 认证守卫：检查用户登录状态
  • 权限守卫：验证用户角色和权限
  • 进度条：路由切换时显示加载进度
sequenceDiagram
participant U as 用户
participant R as 路由守卫
participant A as 认证检查
participant P as 权限检查
participant V as 视图组件
U->>R : 访问路由
R->>A : 检查登录状态
alt 未登录
A-->>R : 重定向到登录页
R-->>U : 跳转登录页
else 已登录
R->>P : 检查权限
alt 无权限
P-->>R : 拒绝访问
R-->>U : 跳转到403页面
else 有权限
P-->>R : 允许访问
R->>V : 加载组件
V-->>U : 显示页面
end
end

图表来源

章节来源

主题与样式系统

新架构采用现代化的主题系统，支持深色模式、主题色定制和响应式设计：

主题架构

  • CSS变量: 全局主题变量定义
  • UnoCSS: 原子化样式引擎，按需生成样式
  • SCSS: 复杂样式逻辑和混合宏
  • 主题预设: 内置多种主题方案

主题特性

  • 实时主题切换
  • 深色/浅色模式自动检测
  • 品牌色自定义
  • 字体大小调节
  • 布局模式切换
graph TB
A["主题配置"] --> B["CSS变量"]
A --> C["UnoCSS预设"]
A --> D["SCSS变量"]
B --> E["组件样式"]
C --> E
D --> E
E --> F["运行时主题切换"]
F --> G["浏览器本地存储"]

图表来源

章节来源

构建与部署

新架构采用Vite 5作为构建工具，配合pnpm workspace实现高效的开发和构建流程：

构建配置

  • 开发环境: 热重载、Source Map、ESLint集成
  • 生产环境: 代码分割、Tree Shaking、资源压缩
  • 多环境配置: 开发、测试、生产环境差异化配置

部署策略

  • Docker容器化部署
  • Nginx反向代理配置
  • CDN静态资源托管
  • 环境变量管理

章节来源

性能优化

新架构在多个层面实施性能优化策略：

代码优化

  • Tree Shaking: 移除未使用的代码
  • 代码分割: 路由级和组件级懒加载
  • 依赖优化: 第三方库按需引入
  • 缓存策略: 浏览器缓存和服务端缓存

运行时优化

  • 虚拟滚动: 大数据列表渲染优化
  • 图片优化: WebP格式、懒加载、CDN加速
  • 内存管理: 组件卸载时清理监听器和定时器
  • 首屏优化: 关键路径代码内联、预加载重要资源

章节来源

开发工作流

新架构提供完整的现代化开发工作流：

开发环境

  • 热重载: 代码修改即时预览
  • 类型检查: 实时TypeScript错误提示
  • 代码格式化: Prettier自动格式化
  • 代码检查: ESLint规则校验

构建脚本

  • 开发服务器: pnpm dev
  • 生产构建: pnpm build
  • 预览构建: pnpm preview
  • 代码检查: pnpm lint
  • 类型检查: pnpm typecheck

章节来源

故障排查指南

新架构提供了完善的调试和故障排查机制：

常见问题

  • TypeScript错误: 检查tsconfig配置和类型定义
  • 构建失败: 查看Vite构建日志和依赖冲突
  • 运行时错误: 使用浏览器开发者工具和错误边界
  • 性能问题: 使用Chrome DevTools分析性能瓶颈

调试技巧

  • Vue DevTools: 组件树、状态、事件调试
  • 网络面板: API请求和响应调试
  • 控制台日志: 结构化日志输出
  • 错误监控: 前端错误收集和上报

章节来源

结论

全新的基于Soybean Admin的前端架构通过monorepo结构、现代化技术栈和完善的开发工作流，显著提升了项目的可维护性、可扩展性和开发效率。新架构不仅解决了旧版本的痛点，还为未来的功能扩展和技术演进奠定了坚实基础。建议团队逐步迁移现有功能到新架构，充分利用TypeScript的类型安全和现代JavaScript生态的优势。

Reference in New Issue View Git Blame Copy Permalink