个人主页项目架构设计

个人主页项目架构设计文档

1. 项目概述

1.1 项目简介

该项目是一个基于 Vue 3 + Node.js + MongoDB 的现代化个人主页系统，采用 Monorepo 架构设计，包含前端展示页面、CMS管理系统和后端API服务。该项目旨在为用户提供一个功能完整、性能优异的个人主页解决方案。

1.2 技术栈

• 前端: Vue 3 + TypeScript + Vite + Pinia + Vue Router
• 后端: Node.js + Express + TypeScript + MongoDB + Mongoose
• 构建工具: Vite + pnpm workspace
• 代码规范: ESLint + Stylelint + Prettier
• 部署: HTTPS + 环境配置

1.3 整体系统架构图

2. 整体架构设计

2.1 Monorepo 架构

项目采用 pnpm workspace 实现 Monorepo 架构，包含以下模块：

home-page-pro/
├── apps/                    # 应用层
│   ├── home-page/          # 个人主页前端应用
│   └── cms-system/         # CMS管理系统前端应用
├── services/               # 服务层
│   └── nodejs/            # 后端API服务
├── packages/               # 共享包
│   ├── components/        # 共享组件库
│   └── shared/           # 共享工具库
└── scripts/               # 构建脚本

2.1.1 Monorepo 架构图

2.2 架构优势

• 代码复用: 通过共享包实现组件和工具的统一管理
• 统一构建: 支持多应用并行构建和部署
• 版本管理: 统一的依赖管理和版本控制
• 开发效率: 支持跨应用的代码共享和热更新

3. 前端架构设计

3.1 技术栈详解

3.1.1 核心框架

• Vue 3: 采用 Composition API，提供更好的 TypeScript 支持和性能优化
• TypeScript: 提供类型安全，提升代码质量和开发体验
• Vite: 现代化的构建工具，支持快速热更新和优化构建

3.1.2 状态管理

• Pinia: Vue 3 官方推荐的状态管理库，替代 Vuex
• 模块化设计: 按功能模块划分 store，如 user、keep-alive 等

3.1.3 路由管理

• Vue Router 4: 支持动态路由和路由守卫
• 路由懒加载: 实现按需加载，优化首屏性能
• Keep-Alive: 支持页面缓存，提升用户体验

3.2 应用架构

3.2.1 Home Page 应用

src/
├── api/                   # API接口层
│   ├── common.ts         # 通用接口
│   ├── experience.ts     # 经历相关接口
│   ├── fragments.ts      # 碎片相关接口
│   └── foundation.ts     # 基础数据接口
├── components/           # 组件层
│   ├── footer-main/      # 页脚组件
│   └── ...              # 其他业务组件
├── views/               # 页面层
│   ├── home/           # 主页
│   ├── sample-chat/    # 聊天页面
│   └── secretary/      # 秘书页面
├── stores/             # 状态管理
│   ├── user.ts         # 用户状态
│   └── keep-alive.ts   # 缓存状态
├── utils/              # 工具层
│   ├── request.ts      # HTTP请求封装
│   └── theme.ts        # 主题管理
└── types/              # 类型定义

3.2.2 CMS System 应用

• 提供内容管理功能
• 支持用户信息、经历、项目等数据的增删改查
• 采用相同的技术栈，确保开发体验一致性

3.3 组件设计

3.3.1 共享组件库 (@mh/components)

• SvgIcon: SVG图标组件，支持动态加载和主题切换
• CopyMain: 复制功能组件，提供统一的复制体验
• BaseCard: 基础卡片组件，提供统一的卡片样式
• BaseDialog: 基础对话框组件，支持自定义内容

3.3.2 业务组件

• LeftMain: 主页左侧内容组件
• RightMain: 主页右侧内容组件
• Timeline: 时间线组件
• SkillTags: 技能标签组件

3.4 状态管理设计

3.4.1 状态管理架构图

3.4.2 User Store

interface State {
  userInfo: User;
  tokenInfo: TokenResponse;
}

// 主要功能
- getTokenInfo(): 获取访问令牌
- getUserInfo(): 获取用户信息
- setTokenInfo(): 设置令牌信息
- setUserInfo(): 设置用户信息

3.4.3 Keep-Alive Store

interface State {
  cachedViews: RouteLocationNormalized[];
}

// 主要功能
- addCacheOnly(): 添加页面缓存
- removeCache(): 移除页面缓存
- clearCache(): 清空所有缓存

3.5 网络请求设计

3.5.1 网络请求架构图

3.5.2 Token管理流程图

3.5.3 请求封装

• Axios 封装: 统一的 HTTP 请求库
• 拦截器设计: 请求和响应拦截器
• 错误处理: 统一的错误处理机制
• Token 管理: 自动刷新 token 机制

3.5.4 核心特性

// 自动刷新 Token
- 检测 token 过期时间
- 自动刷新即将过期的 token
- 请求队列管理，避免重复刷新

// 错误处理
- HTTP 状态码处理
- 业务错误码处理
- 网络错误处理
- 超时处理

4. 后端架构设计

4.1 技术栈详解

4.1.1 核心框架

• Express 5: 现代化的 Node.js Web 框架
• TypeScript: 提供类型安全和更好的开发体验
• MongoDB + Mongoose: NoSQL 数据库和 ODM
• JWT: 基于 Token 的身份认证

4.1.2 中间件设计

• CORS: 跨域资源共享配置
• Body Parser: 请求体解析
• Rate Limiting: 请求频率限制
• Response Header: 响应头设置

4.2 后端分层架构图

4.3 项目结构

src/
├── app.ts                 # 应用入口
├── config/               # 配置文件
│   └── default.ts        # 默认配置
├── controller/           # 控制器层
│   ├── user.controller.ts
│   ├── auth.controller.ts
│   └── ...
├── service/              # 服务层
│   ├── user.service.ts
│   └── ...
├── models/               # 数据模型层
│   ├── user.model.ts
│   └── ...
├── routes/               # 路由层
│   ├── index.ts
│   ├── user.route.ts
│   └── ...
├── middleware/           # 中间件层
│   ├── index.ts
│   ├── validate.ts
│   └── dynamicToken.ts
├── decorators/           # 装饰器
│   └── route.decorator.ts
├── utils/                # 工具层
│   ├── db-connect.ts
│   ├── jwt.ts
│   └── logger.ts
└── types/                # 类型定义

4.3 分层架构设计

4.3.1 控制器层 (Controller)

• 职责: 处理 HTTP 请求和响应
• 特点: 使用装饰器模式，简化路由定义
• 功能: 参数验证、权限控制、响应格式化

@Controller('/v1/user')
export class UserController {
  @Get('/find', { requireAuth: true })
  async getUser(req: Request, res: Response): Promise<void> {
    // 业务逻辑
  }
}

4.3.2 服务层 (Service)

• 职责: 业务逻辑处理
• 特点: 提供 CRUD 操作的统一接口
• 功能: 数据验证、业务规则、数据转换

4.3.3 模型层 (Model)

• 职责: 数据模型定义和数据库操作
• 特点: 使用 Mongoose Schema 定义数据结构
• 功能: 数据验证、索引优化、关联查询

4.3.4 中间件层 (Middleware)

• 职责: 请求预处理和后处理
• 特点: 模块化设计，可组合使用
• 功能: 认证、授权、日志、错误处理

4.4 认证授权设计

4.4.1 JWT认证流程图

4.4.2 JWT Token 机制

JWT是由 Header(算法信息)、Payload(用户数据)、signature(签名) 组成。其中 Payload(用户数据)主要包含以下信息：

// Token 结构
interface TokenPayload {
  clientId: string; // 客户端标识
  customerId: string; // 用户标识
  type: 'access' | 'refresh';
  iat: number; // 签发时间
  exp: number; // 过期时间
}

// Token 生成
- generateAccessToken(): 生成访问令牌
- generateRefreshToken(): 生成刷新令牌
- generateClientId(): 生成客户端标识

4.4.3 权限控制

• 基于 Token 的认证: 每个请求都需要有效的访问令牌
• 动态 Token 验证: 支持不同客户端的独立认证
• Token 刷新机制: 自动刷新即将过期的令牌

4.5 数据库设计

4.5.1 MongoDB 集合设计

// 用户集合 (users)
interface User {
  _id: ObjectId;
  customerId: string;
  name: string;
  email: string;
  tel: string;
  wx: string;
  gitee: string;
  resume: string;
  createAt: Date;
  updateAt: Date;
}

// 经历集合 (experiences)
interface Experience {
  _id: ObjectId;
  customerId: string;
  title: string;
  description: string;
  startDate: Date;
  endDate: Date;
  hasProjects: boolean;
  createAt: Date;
  updateAt: Date;
}

// 项目集合 (projectExperiences)
interface ProjectExperience {
  _id: ObjectId;
  experienceId: ObjectId;
  title: string;
  description: string;
  technologies: string[];
  createAt: Date;
  updateAt: Date;
}

4.5.2 数据关联

• 一对多关系: 用户 -> 经历 -> 项目
• 索引优化: 在 customerId 和 experienceId 上建立索引
• 数据一致性: 通过外键约束保证数据完整性

5. 构建和部署架构

5.1 构建系统

5.1.1 Vite 配置

// 核心插件
- @vitejs/plugin-vue: Vue 3 支持
- @vitejs/plugin-vue-jsx: JSX 支持
- vite-plugin-svg-icons: SVG 图标支持
- vite-plugin-compression: 代码压缩
- vite-plugin-eslint: ESLint 集成

5.1.2 环境配置

• 开发环境: 本地开发服务器，支持热更新
• 生产环境: 代码压缩、资源优化、CDN 部署
• 多环境支持: 通过 .env 文件管理不同环境配置

5.2 部署架构

5.2.1 部署架构图

5.2.1 前端部署

• 静态资源: 部署到 CDN 或静态服务器
• 路由配置: 支持 SPA 路由的服务器配置
• 缓存策略: 静态资源长期缓存，API 请求不缓存

5.2.2 后端部署

• HTTPS 支持: 生产环境使用 SSL 证书
• 负载均衡: 支持多实例部署
• 日志管理: 使用 Pino 进行结构化日志记录

5.3 监控和运维

5.3.1 日志系统

• 结构化日志: 使用 Pino 记录结构化日志
• 错误追踪: 统一的错误处理和日志记录
• 性能监控: 请求响应时间监控

5.3.2 健康检查

• 数据库连接: 定期检查数据库连接状态
• API 健康: 提供健康检查接口
• 资源监控: 内存和 CPU 使用率监控

6. 安全设计

6.1 前端安全

• XSS 防护: 输入输出过滤和 CSP 策略
• CSRF 防护: Token 验证和 SameSite Cookie
• 敏感信息保护: 不在前端存储敏感信息

6.2 后端安全

• 输入验证: 使用 Zod 进行参数验证
• SQL 注入防护: 使用 Mongoose 进行参数化查询
• 权限控制: 基于 Token 的细粒度权限控制
• 速率限制: 防止 API 滥用

6.3 数据传输安全

• HTTPS: 生产环境强制使用 HTTPS
• Token 安全: JWT Token 加密和过期机制
• 敏感数据: 敏感数据加密存储

7. 性能优化

7.1 前端性能优化

• 代码分割: 路由级别的代码分割
• 懒加载: 组件和图片的懒加载
• 缓存策略: 合理的缓存策略设计
• 资源优化: 图片压缩和格式优化

7.2 后端性能优化

• 数据库优化: 索引优化和查询优化
• 缓存机制: Redis 缓存热点数据
• 连接池: 数据库连接池管理
• 异步处理: 非阻塞的异步操作

8. 开发流程

8.1 Git工作流图

8.2 代码规范

• ESLint: JavaScript/TypeScript 代码规范
• Stylelint: CSS/SCSS 代码规范
• Prettier: 代码格式化
• Git Hooks: 提交前自动检查

8.3 版本控制

• Git Flow: 基于 Git Flow 的分支管理
• 语义化版本: 遵循语义化版本规范
• 变更日志: 维护详细的变更日志

8.4 测试策略

• 单元测试: 核心业务逻辑的单元测试
• 集成测试: API 接口的集成测试
• E2E 测试: 端到端的用户场景测试

9. 总结

该项目采用现代化的技术栈和架构设计，具有以下特点：

9.1 技术栈对比图

9.2 技术优势

• 现代化技术栈: Vue 3 + TypeScript + Node.js
• Monorepo 架构: 统一的代码管理和构建流程
• 类型安全: 全面的 TypeScript 支持
• 性能优化: 多层次的性能优化策略

9.3 架构优势

• 模块化设计: 清晰的模块划分和职责分离
• 可扩展性: 支持功能模块的灵活扩展
• 可维护性: 良好的代码组织和文档支持
• 安全性: 多层次的安全防护机制

9. 开发体验

• 开发效率: 热更新、类型提示、代码规范
• 调试便利: 完善的日志和错误处理
• 部署简单: 自动化的构建和部署流程
• 团队协作: 统一的开发规范和工具链

该项目为个人主页系统提供了一个完整、现代化、可扩展的解决方案，适合作为个人或小型团队的项目基础架构。