第六章. 前端项目结构 (plus-ui) 总览

第六章. 前端项目结构 (plus-ui) 总览

摘要：本章我们将快速浏览 plus-ui（基于 Vue 3 和 Vite）的前端项目结构。我们将重点识别根目录的核心配置文件和 src 源码目录下的关键文件夹，目标是建立一个清晰的“前端地图”，知道不同功能的代码（如 API, 页面, 状态管理）存放在哪里。

本章学习路径

在上一章掌握了后端“地图”后，本章我们将用最短的时间熟悉前端“地图”。我们将采用“由外到内”的方式：

前端项目结构总览

学习建议：

  • 本章的目的是“速览”而非“精通”。我们暂时不深入 Vue 3 或 TypeScript 的语法细节，重点是记住各个文件夹的职责，这会为我们后续修改前端页面、对接后端接口打下基础。

6.1. 根目录：项目配置与构建核心

在上一章中，我们已经完整解构了 RuoYi-Vue-Plus 后端的四大模块组，掌握了其分层与聚合的设计哲学。但一个完整的系统离不开前端的呈现，后端的 ruoyi-admin 最终是为前端 plus-ui 服务的。本节我们就从 plus-ui 项目的根目录开始，快速了解支撑这个现代化前端应用运行的核心配置文件。

6.1.1. 包管理与依赖：package.json 与 node_modules

文件/目录职责核心作用
package.json项目“身份证”1. scripts: 定义了 dev (启动)、build:prod (打包) 等快捷命令。
2. dependencies: 声明项目 生产环境 必需的依赖（如 vue, axios, pinia）。
3. devDependencies: 声明 开发环境 才用的依赖（如 vite, typescript, eslint）。
node_modules/本地依赖库存放 npm install 命令根据 package.json 下载的所有依赖的 实际代码。
注意：这个目录体积巨大（几百 MB），绝对不能 提交到 Git 仓库（已在 .gitignore 中配置忽略）。
package-lock.json依赖“锁仓”文件锁定 npm install 时安装的 确切版本号，确保团队所有成员和服务器上安装的依赖版本 完全一致，避免“在我这能跑”的问题。

6.1.2. 构建与编译核心：Vite, TypeScript 与 UnoCSS

配置文件职责核心作用
vite.config.ts项目构建器 (Vite)Vite 的核心配置。定义了启动、打包、代理（proxy，用于跨域请求后端）、插件（plugins）等所有构建行为。5.x 版本极快的启动速度（秒级）就得益于 Vite。
tsconfig.jsonTypeScript 编译器TS 的核心配置。告诉 TypeScript 编译器如何检查和转译代码。例如，它定义了 paths 别名（如 @/ 指向 src/）和严格性检查规则。
uno.config.ts原子化 CSS 引擎UnoCSS 的核心配置。UnoCSS 是一个高性能的原子化 CSS 引擎，允许我们像写 class="text-left" 这样快速编写样式，它负责按需生成最终的 CSS 文件。
vite/ 目录Vite 插件配置plus-ui 将 vite.config.ts 中复杂的插件（如自动导入、图标、压缩）抽离到了这个目录中，统一管理，保持主配置文件的简洁。

6.1.3. 代码规范与环境：ESLint, Prettier 与 .env

配置文件职责（是什么）核心作用（为什么重要）
eslint.config.ts代码质量检查 (ESLint)负责 检查代码语法和潜在错误。例如，它会警告你“定义了变量但未使用”，保证代码的健壮性。
prettier.config.js代码风格格式化 (Prettier)负责 统一代码风格（如使用单引号、行尾加分号、缩进空格数）。与 .editorconfig 配合，保证团队代码风格一致。
.gitignoreGit 忽略配置告诉 Git 不要提交 node_modules/、dist/ (打包产物)、.env.* (本地配置) 等文件。
.env.development
.env.production		环境变量非常重要。定义不同环境下的变量。
VITE_APP_BASE_API 是最关键的配置，用于指定 后端 API 的地址（如开发时代理到 http://localhost:8080）。

6.1.4. 应用入口与公共资源：index.html 与 public

  • index.html (应用入口)
    • 这是整个 Vue 应用的 唯一 HTML 页面，也是浏览器的访问入口。
    • 它的 <body> 中只有一个 <div id="app"></div>。Vue 启动后，会将 App.vue 组件渲染并挂载到这个 div 上，从而“接管”整个页面。
  • public/ (公共静态资源)
    • 存放 不会被 Vite 处理 的静态资源。
    • 最典型的是 favicon.ico（浏览器标签页的小图标）。

6.1.5. 本节小结

我们快速扫描了 plus-ui 根目录下的核心配置文件，现在我们知道了：

  • 包管理：package.json 定义了“需要什么依赖”，npm install 负责下载到 node_modules。
  • 构建核心：vite.config.ts 是 构建器，负责启动和打包；tsconfig.json 负责 TS 编译；uno.config.ts 负责 CSS。
  • 开发规范：eslint 查错，prettier 保证风格，.gitignore 防止提交“垃圾”。
  • 环境配置：.env.development 等文件定义了环境变量，尤其是 后端 API 地址 VITE_APP_BASE_API。
  • 应用入口：浏览器访问 index.html，Vue 应用被挂载到 <div id="app"></div>。

6.2. src 核心代码目录解析（上）：应用启动与页面

在上一节中，我们已经熟悉了 plus-ui 根目录下的所有“配置文件”，它们是项目运行和构建的“地基”。现在，是时候踏入真正的“大楼”内部了——src 目录。src (Source，源码) 目录存放了 100% 的前端业务代码。本节我们首先聚焦于应用是如何“启动”和“组织页面”的。

6.2.1. 应用启动铁三角：main.ts, App.vue, permission.ts

这三个文件是 plus-ui 应用启动和运行的“发动机”：

  1. main.ts (应用总入口)

    • 职责：Vue 应用的启动入口文件，也是最先执行的 ts 脚本。
    • 核心作用：它负责创建 Vue 应用实例，并将所有必要的“插件”和“配置”在应用启动前“安装”好。
    • 主要工作：
      • 创建 Vue 实例：createApp(App)
      • 挂载根组件：将 App.vue 挂载到 index.html 的 #app 元素上。
      • 安装插件：app.use(...)，例如安装 router (路由)、pinia (状态管理)、Element Plus (UI 库) 以及自定义插件 (如 src/plugins 下的工具)。

  2. App.vue (根组件)

    • 职责：Vue 应用的根组件。
    • 核心作用：它是所有页面内容的“容器”。
    • 主要工作：它内部只包含一个核心组件 <router-view />。这个组件的含义是：“根据当前浏览器的 URL，把我匹配到的页面（views 目录下的某个 .vue 文件）显示在这个位置”。

  3. permission.ts (权限控制)

    • 职责：全局路由守卫（俗称“路由拦截器”）。
    • 核心作用：它是实现前端登录鉴权和页面访问控制的核心。
    • 主要工作：
      • 白名单：定义 /login 等无需登录即可访问的页面。
      • 登录拦截：在每次路由跳转前（router.beforeEach）进行检查。
      • Token 校验：检查本地是否存有 Token（登录凭证）。如果用户未登录（无 Token）却试图访问非白名单页面，则强制重定向到 /login 登录页。
      • 权限加载：如果用户已登录，它会触发 store (状态管理) 去后端获取用户信息和菜单路由。

6.2.2. 页面与布局：views, layout, router

如果说“铁三角”是发动机，那 views, layout, router 就是大楼的“房间”、“框架”和“导航地图”。

目录/文件职责（是什么）核心作用（为什么重要）
views/页面组件目录存放所有“页面”级别的 .vue 文件。每一个菜单项点击后展示的主内容区，都对应 views 里的一个文件。例如：
- views/system/user/index.vue (用户管理页面)
- views/login.vue (登录页)
layout/主框架布局负责渲染非内容区域的“框架”，即系统的顶部导航栏、侧边菜单栏和标签页（TagsView）。
layout/index.vue 是主布局文件，它内部会嵌套 <AppMain> (主内容区)，而 <AppMain> 内部又会嵌套 <router-view />，最终将 views/ 里的页面渲染进来。
router/路由配置URL 与页面的“导航地图”。
router/index.ts 文件定义了所有路由规则，即：“当用户访问 /system/user 这个 URL 时，我应该在 layout 框架内，加载 views/system/user/index.vue 这个页面组件”。

关键流程：用户登录 -> permission.ts 放行 -> router/ 匹配 URL -> layout/ 渲染框架 -> views/ 渲染页面内容 -> App.vue 最终呈现。

6.2.3. 本节小结

我们理清了 src 目录（上）中关于“启动”和“页面”的部分：

  • 启动：由 main.ts (入口) 创建 Vue 实例，加载 App.vue (根组件)。
  • 权限：permission.ts (路由守卫) 负责在页面跳转前进行登录和权限拦截。
  • 组织：router/ (路由) 定义 URL 和页面的映射关系。
  • 呈现：layout/ (布局) 负责渲染框架（菜单栏、导航栏），views/ (页面) 负责渲染业务内容，两者最终组合呈现在用户面前。

6.3. src 核心代码目录解析（下）：数据与复用

在上一节中，我们已经清晰了 src 目录是如何启动和组织页面的（main.ts, views, router, layout）。但一个页面如果只有静态内容（views）而没有数据（api）和状态（store），那是没有意义的。本节我们将探索 src 目录的其余部分，看看前端的“数据”从哪来，以及“可复用的代码”如何组织。

6.3.1. 数据管理：api, store, enums

这三个目录是前端的“数据中枢”：

目录职责（是什么）核心作用（为什么重要）
api/后端接口请求100% 的后端 API 请求都封装在这里。它使用 axios（封装在 utils/request.ts）向后端发起请求。
强规范：api 目录的结构与后端的 controller 严格对应。例如：
- api/system/user.ts 对应 ruoyi-system 的 SysUserController。
store/全局状态管理 (Pinia)存放全局“共享”数据。当 A 页面需要与 B 页面共享数据，或数据需要跨页面持久化时，就使用 store (基于 Pinia)。
核心模块：
- store/modules/user.ts: 存储用户信息、Token。
- store/modules/permission.ts: 存储用户菜单和路由。
enums/前端枚举存放前端的枚举或常量。用于统一管理在代码中多处使用的“魔法值”（如 LanguageEnum.ts）。

6.3.2. 公共能力：assets, components, utils, hooks

这四个目录是前端的“工具箱”和“零件库”，用于存放可复用的资源和逻辑：

目录职责（是什么）核心作用（为什么重要）
assets/静态资源存放会被 Vite/Webpack 打包的静态资源。如 logo.png、全局 SCSS 样式（styles/）、SVG 图标（icons/svg/）等。
components/公共组件存放可复用的“UI 零件”（.vue 文件）。这些组件不是页面，而是组成页面的“小块”。
例如：Pagination (分页)、ImageUpload (图片上传)、SvgIcon (图标)。
utils/工具函数存放与 UI 无关的、纯粹的 JavaScript / TypeScript 工具函数。
例如：utils/request.ts (封装 axios 请求)、utils/validate.ts (表单校验)、utils/auth.ts (Token 存取)。
hooks/自定义钩子 (Hooks)存放 Vue 3 可组合的逻辑函数 (Composition API)。用于抽离可复用的带状态的逻辑。
例如：hooks/useDialog.ts (封装了对话框常用的 open, close, title 等状态)。
directive/自定义指令存放 Vue 的自定义指令，如 v-permission（按钮权限控制）、v-copyText（一键复制）。
plugins/Vue 插件封装 Vue 插件，如 plugins/modal.ts (封装弹窗 Message 和 Notification)，然后在 main.ts 中 app.use() 全局安装。

6.3.3. 本节小结

我们探索了 src 目录的“数据”和“复用”部分：

  • 数据来源：api/ 目录负责从后端获取数据。
  • 数据管理：store/ (Pinia) 负责全局共享数据（如用户信息）；enums/ 负责管理常量。
  • 代码复用：
    • components/ 存放复用的 UI 组件。
    • utils/ 存放复用的 JS/TS 工具函数。
    • hooks/ 存放复用的 Vue 3 组合逻辑。
    • assets/ 存放复用的静态资源（图片、样式）。

6.4.本章总结

第六章我们快速扫描了 plus-ui 前端项目的“地图”。虽然没有深入代码，但我们现在对整个项目的结构有了清晰的认知，这为后续的开发和调试扫清了障碍。

我们“由外到内”地解构了整个项目：

  1. 根目录（配置层）：我们了解了项目是如何通过 package.json（依赖）、vite.config.ts（构建）、tsconfig.json（编译）、.env（环境）、eslint（规范）等文件组织和管理起来的。
  2. src 目录（启动层）：我们知道了 main.ts 是入口，它加载了 App.vue（根组件）。permission.ts（权限守卫）则在 router/（路由）跳转前进行登录拦截。
  3. src 目录（视图层）：我们明确了 layout/ 负责渲染“框架”（菜单栏、导航栏），而 views/ 负责渲染具体的“页面内容”。
  4. src 目录（数据层）：我们知道了 api/ 负责对接后端接口（100% 的数据来源），store/ (Pinia) 负责管理全局共享状态（如 Token 和用户信息）。
  5. src 目录（复用层）：我们区分了 components/（公共 UI 组件）、utils/（公共 JS 工具）、hooks/（公共 Vue 逻辑）和 assets/（公共静态资源）。

实战蓝图 (二次开发指南)

学完本章，当你需要修改前端时，你应该能立即定位到文件：

需求场景应该去哪里修改？
1. 修改“用户管理”页面的表格样式src/views/system/user/index.vue
2. 修改“用户管理”获取列表的接口参数src/api/system/user.ts
3. 修改登录成功后存储 Token 的方式src/store/modules/user.ts
4. 修改左侧菜单栏的 Logosrc/layout/components/Sidebar/Logo.vue (组件) 和 src/assets/logo/logo.png (图片)
5. 新增一个“商城管理”一级菜单1. src/router/index.ts (定义路由)
2. src/views/mall/index.vue (创建页面)
(注：在 RVP 中，菜单由后端 sys_menu 表动态生成，前端只需在可视化页面生成即可
6. 修改后端 API 服务的地址根目录的 .env.development 文件（修改 VITE_APP_BASE_API）
7. 封装一个全局“时间格式化”工具src/utils/ (新建一个 date.ts 或在 index.ts 中添加)
8. 封装一个全局“防止重复点击”的按钮src/directive/ (新建 preventReClick.ts)

知识盲点自查表

不看笔记，尝试回答以下问题：

  1. （填空）前端项目的总入口文件是 _________，它会加载根组件 _________。
  2. （填空）所有后端接口的请求都必须封装在 _________ 目录中。
  3. （填空）负责全局路由拦截（登录鉴权）的文件是 _________。
  4. （填空）存放全局共享数据（如用户信息和 Token）的目录是 _________，它基于 _________ 状态管理库。
  5. （填空）views/ 目录存放 _________，而 components/ 目录存放 _________。
  6. （填空）Vite 的核心配置文件是 _________，而定义后端 API 地址的文件是 _________。
  1. src/main.ts，src/App.vue。
  2. src/api/。
  3. src/permission.ts。
  4. src/store/，Pinia。
  5. views/ 存放 页面级组件，components/ 存放 可复用的公共组件。
  6. vite.config.ts，.env.development (或 .env.production)。