# 4.5 前端分层架构

:::tip 概述
前端按"视图 → 状态 → 接口 → 信封"分层：views 页面消费 store 与 api 模块，api 模块经 http 封装发请求，拦截器统一处理 Token、信封解包与错误提示。
:::

## 请求方向的分层

```text
views/           页面（ElementPlus 组件 + 业务交互）
   │ 消费
   ├── store/     Pinia（用户身份、动态路由、标签页、设置）
   └── api/       接口模块（按业务域分组，一模块一文件）
        │ 调用
        ▼
utils/http/      axios 封装（拦截器）
        │  请求拦截：Token 注入、前缀拼接
        │  响应拦截：信封解包、错误统一提示、401 处理
        ▼
/api/**          后端统一信封
```

## 静态支撑层

| 目录 | 职责 |
|---|---|
| router/ | 静态路由 + generator-routers（菜单 API → 路由表）+ router-guards（守卫） |
| layout/ | 布局（侧边栏、顶栏、标签页、面包屑） |
| components/ | 公共组件（Table/Page/Form/Upload/Editor/Excel 等 28 个） |
| directives/ | 自定义指令（permission 按钮显隐等） |
| composables/hooks/ | 组合式函数（useTime、useOnline、web/setting/event 分组） |
| enums/ | 前端枚举常量（http/role/permissions/cache/page/breakpoint/avatar） |
| utils/ | 纯工具（auth、validate、format、download、color、dom...） |
| styles/ | 全局样式与主题变量 |
| settings/ | 应用级默认设置 |

## 与后端的三个契约点

| 契约 | 前端落点 | 后端落点 |
|---|---|---|
| 字段名 | 请求/响应对象小驼峰 | dto json 标签 |
| 信封 | 拦截器解包 data，ok=false 弹 msg | response 中间件 |
| 权限 | v-perm / v-perms 指令比对权限码 | RouteSpec.Permission + 菜单节点 |

前端不硬编码枚举显示名——字典项经字典接口获取（与后端 SerializeMaps 同口径）。

## 动态路由流水线

```text
登录 → 拉取 /api/index/getMenus（按角色过滤的菜单树）
   → asyncRoute store 生成路由表
   → router.addRoute 逐条注入
   → 布局按路由表渲染侧边栏
```

菜单表的 path/component 字段直接映射前端路由与 `views` 下组件路径——后端菜单管理即前端路由管理，无需前端改代码。

## 分层规约

| 层 | 禁止 |
|---|---|
| views | 直接 axios、写信封判断逻辑（交给 http 封装） |
| api | 出现 UI 逻辑、持有 Token |
| store | 放可从接口推导的数据 |
| components | 耦合具体业务模块（放 views 下 components） |

深入开发见 [第 9 章 前端开发](/zh/frontend/overview.html)。

## 下一步

→ [4.6 目录结构设计](/zh/architecture/directory-design.html)