200 lines
14 KiB
Markdown
200 lines
14 KiB
Markdown
# Chat Demo 前端设计书
|
||
|
||
## 1. 文档说明
|
||
|
||
本文档依据当前仓库中的前端代码，说明系统目标、技术选型、模块边界、代码结构、主要数据流和交互设计。项目是一个 Vue 单页聊天演示前端；当前仓库不包含服务端实现，因此服务端接口及消息协议以客户端实际调用和解析的内容为准。
|
||
|
||
## 2. 项目概述
|
||
|
||
系统提供账号注册、登录和一对一即时聊天页面。用户登录后可以查看最近会话、搜索最近联系人、浏览联系人在线状态、查看历史消息、加载更早消息，并通过 WebSocket 收发消息。聊天页面采用三栏布局：功能导航、会话/联系人列表、当前聊天内容。
|
||
|
||
前端职责包括：
|
||
|
||
- 通过 REST API 完成注册、登录以及用户、联系人、会话和历史消息数据读取。
|
||
- 保存登录令牌，并在后续 HTTP 请求中携带令牌。
|
||
- 使用 Vue Router 限制聊天路由的访问。
|
||
- 建立 WebSocket 连接，发送聊天消息、处理服务端推送并回传消息确认 ACK。
|
||
- 管理页面内的会话、消息、未读数、在线用户和输入状态。
|
||
|
||
## 3. 技术选型
|
||
|
||
| 分类 | 技术/模块 | 用途 |
|
||
| --- | --- | --- |
|
||
| UI 框架 | Vue 2.6 | 页面组件与响应式视图，采用 Options API |
|
||
| 路由 | Vue Router 3 | `/login`、`/register`、`/chat` 页面切换及导航守卫 |
|
||
| 状态管理 | Vuex 3 | 保存 token 和当前用户名 |
|
||
| UI 组件 | Element UI 2 | 登录/注册表单、输入框、按钮、提示消息 |
|
||
| HTTP | Axios 1 | REST 请求、认证请求头、统一响应与 401 处理 |
|
||
| 实时通信 | 浏览器原生 WebSocket | 即时消息、在线用户列表和 ACK |
|
||
| 构建工具 | Vue CLI 5、Babel 7 | 本地开发、构建、ES 转译和 Element UI 组件按需样式处理 |
|
||
|
||
项目未使用 TypeScript、独立 API 状态库或 WebSocket 第三方库；聊天页面自身维护主要业务状态。
|
||
|
||
## 4. 总体架构
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Browser[浏览器] --> Entry[src/main.js]
|
||
Entry --> App[src/App.vue]
|
||
Entry --> Router[src/router.js]
|
||
Entry --> Store[src/store/index.js]
|
||
Router --> Pages[登录 / 注册 / 聊天页面]
|
||
Pages --> API[src/utils/api.js]
|
||
API --> Request[src/utils/request.js]
|
||
Request -->|HTTP /api| Backend[后端 localhost:3000]
|
||
Pages --> WS[src/utils/websocket.js]
|
||
WS -->|WebSocket ws://localhost:3000| Backend
|
||
Request --> Store
|
||
Router --> Store
|
||
```
|
||
|
||
页面层负责交互、视图状态和流程编排；`api.js` 将业务接口映射为 HTTP 方法；`request.js` 统一管理 Axios 配置和拦截器；`websocket.js` 封装浏览器 WebSocket 的创建、发送、关闭和回调。Vuex 在入口、路由和请求层之间共享认证状态。
|
||
|
||
## 5. 代码结构与模块职责
|
||
|
||
```text
|
||
.
|
||
├── public/
|
||
│ └── index.html # SPA HTML 宿主
|
||
├── src/
|
||
│ ├── main.js # Vue、路由、store、Element UI 与全局 CSS 初始化
|
||
│ ├── App.vue # 根组件，通过 router-view 渲染当前页面
|
||
│ ├── router.js # 路由表与 token 路由守卫
|
||
│ ├── store/
|
||
│ │ └── index.js # token、username 与 mutations
|
||
│ ├── pages/
|
||
│ │ ├── login/
|
||
│ │ │ ├── LoginPage.vue # 登录表单和登录后跳转
|
||
│ │ │ └── RegisterPage.vue # 注册表单和密码确认
|
||
│ │ └── index/
|
||
│ │ └── ChatPage.vue # 聊天布局、会话状态及实时消息处理
|
||
│ ├── utils/
|
||
│ │ ├── api.js # 登录、注册、用户和聊天 REST API
|
||
│ │ ├── request.js # Axios 实例、认证头和响应拦截器
|
||
│ │ └── websocket.js # WebSocket 生命周期和 JSON 消息封装
|
||
│ └── assets/css/
|
||
│ └── style_public.css # 全局重置与基础样式
|
||
├── babel.config.js # Vue CLI Babel preset 与 Element UI 按需样式
|
||
├── jsconfig.json # JavaScript 配置及 @ -> src 别名
|
||
├── vue.config.js # Vue CLI 开发服务器代理
|
||
└── package.json # 依赖和开发/构建/lint 命令
|
||
```
|
||
|
||
### 5.1 应用启动与路由
|
||
|
||
`src/main.js` 加载 Element UI 及其主题样式、全局公共 CSS，并将 router 和 store 注入 Vue 根实例。`App.vue` 只提供 `router-view` 容器。路由采用 history 模式：根路径跳转 `/login`；`/login`、`/register` 和 `/chat` 分别对应登录、注册和聊天页面。`/chat` 标记 `requiresAuth`，导航守卫通过 `store.state.token` 判断是否允许进入。
|
||
|
||
### 5.2 登录、注册与认证状态
|
||
|
||
登录页收集用户名和密码，调用 `login()`；成功后从响应中读取 token，提交 `SET_TOKEN`、`SET_USERNAME` 并跳转聊天页。注册页在前端检查两次密码一致后调用 `register()`，成功后返回登录页。
|
||
|
||
Vuex 当前包含：
|
||
|
||
| 状态 | 初始值/持久化 | 用途 |
|
||
| --- | --- | --- |
|
||
| `token` | 初始化时从 `localStorage` 读取；`SET_TOKEN` 同步写入 localStorage | 路由鉴权及请求认证 |
|
||
| `username` | 空字符串，登录时写入 Vuex，不持久化 | 当前会话中的用户标识 |
|
||
|
||
HTTP 请求拦截器从 localStorage 读取 token 并设置 `Authorization` 请求头。响应状态为 401 时清理 token 和用户名并跳转登录页。退出登录时关闭 WebSocket、清空 Vuex token/username 并跳转登录。
|
||
|
||
### 5.3 REST API 封装
|
||
|
||
`src/utils/api.js` 提供以下调用：
|
||
|
||
| 函数 | 方法与路径 | 当前用途 |
|
||
| --- | --- | --- |
|
||
| `login(data)` | `POST /login` | 登录并取得 token |
|
||
| `register(data)` | `POST /register` | 创建账号 |
|
||
| `getUserInfo()` | `GET /userInfo` | 读取当前用户资料 |
|
||
| `getContactInfo()` | `GET /contactsInfo` | 读取联系人列表 |
|
||
| `getRecentMessages()` | `GET /recentChats` | 读取最近会话及预览信息 |
|
||
| `getContactMessages(data)` | `POST /contactMessagesInfo` | 分页读取指定联系人的消息 |
|
||
| `sendMessage(data)` | `POST /sendMessage` | HTTP 发送接口；当前聊天页未使用，实际发送走 WebSocket |
|
||
|
||
`src/utils/request.js` 创建 Axios 实例，默认 `baseURL` 为 `/api`，超时为 10 秒。开发服务器将 `/api` 转发到 `http://localhost:3000`。响应拦截器返回 `response.data`；页面代码随后通过 `response.data` 读取业务字段，因此当前前后端约定应在 HTTP 响应外层提供 `data` 字段（例如 Axios 响应体为 `{ "data": { ... } }`）。由于服务端代码不在本仓库，实际响应格式仍需与后端核对。
|
||
|
||
### 5.4 聊天页面与状态
|
||
|
||
`ChatPage.vue` 以一个组件承载聊天主界面及其业务流程，关键状态如下：
|
||
|
||
| 状态 | 含义 |
|
||
| --- | --- |
|
||
| `currentUser` | 当前用户资料 |
|
||
| `contactList` | 联系人列表 |
|
||
| `recentChats` | 最近会话列表，包含最近消息预览与未读数 |
|
||
| `onlineList` | 服务端推送的在线用户名列表 |
|
||
| `currentContact` | 当前正在查看的联系人 |
|
||
| `contactMessages` | 当前会话中展示的消息数组 |
|
||
| `searchText`、`messageText` | 联系人搜索关键字和编辑中的消息 |
|
||
| `activeMenu` | messages、contacts、settings 侧栏菜单状态 |
|
||
| `firstLoad`、`loadingMore`、`loadEnd` | 历史消息初次加载、分页加载和加载结束标记 |
|
||
|
||
组件创建时并行触发当前用户资料、最近会话和 WebSocket 初始化。最近会话加载完成后，如果列表非空，会自动选择第一条会话。切换至联系人菜单时另行请求联系人列表。选择联系人时清空当前消息并请求首批 10 条，查看后将该联系人未读数清零。
|
||
|
||
历史消息使用 `limit=10`，`offset` 取当前消息条数。加载更早消息时将返回数据倒序后置于现有列表之前，并依据加载前后的滚动区域高度调整 `scrollTop`，以尽量保持用户正在阅读的位置。发送或收到当前会话消息后，视图滚动到底部。
|
||
|
||
### 5.5 WebSocket 实时通信
|
||
|
||
`src/utils/websocket.js` 持有模块级 WebSocket 实例，连接地址固定为 `ws://localhost:3000`。聊天页面从 Vuex 读取 token，去除可能存在的 `Bearer ` 前缀并 URL 编码，通过查询参数 `token` 传递。连接建立后以 JSON 收发消息，并将解析后的数据交给页面回调。
|
||
|
||
客户端当前使用/处理的消息类型：
|
||
|
||
| 类型 | 方向 | 处理方式 |
|
||
| --- | --- | --- |
|
||
| `sendMessage` | 客户端 -> 服务端 | 包含 `messageId`、`senderName`、`receiverName`、`content`、`createdAt`；成功写入本地当前消息列表并更新最近会话 |
|
||
| `newMessage` | 服务端 -> 客户端 | 从 `message` 读取消息；当前联系人消息加入聊天列表，其他联系人的消息更新最近会话和未读数 |
|
||
| `ack` | 客户端 -> 服务端 | 收到 `newMessage` 后按 `messageId` 确认 |
|
||
| `sendError` | 服务端 -> 客户端 | 提示发送失败 |
|
||
| `userOnline` | 服务端 -> 客户端 | 使用 `userList` 更新在线列表 |
|
||
|
||
上述字段是前端代码所依赖的协议，不代表后端已实现或经过端到端验证。`connectWebSocket` 提供 open、close、error 回调；聊天页实现了 open 和 error 处理，未提供 close 回调。发送时要求连接处于 OPEN 状态；否则封装仅写控制台，不抛出异常，因此页面的 try/catch 不能据此判断 WebSocket 是否真正发送成功。
|
||
|
||
### 5.6 UI 与样式
|
||
|
||
聊天页面采用固定宽度左侧导航栏（78px）、联系人面板（300px）和弹性聊天面板。聊天面板包含会话标题、消息滚动区、输入区。消息区区分本人和对方消息气泡，并展示时间；未读数和联系人在线状态通过独立样式表达。页面 CSS 以 `ChatPage.vue` 内的 scoped 样式为主，公共 CSS 提供基础重置。
|
||
|
||
登录和注册页使用 Element UI 表单控件，页面样式局部定义，窄屏时缩小表单内边距。聊天容器设置 `min-width: 980px`，当前小屏行为是保留最小宽度并可能产生横向溢出，不属于完整的移动端适配。
|
||
|
||
## 6. 主要业务流程
|
||
|
||
### 6.1 登录进入聊天
|
||
|
||
1. 用户提交用户名和密码，页面调用 `POST /api/login`。
|
||
2. 成功响应中的 token 写入 Vuex 和 localStorage，用户名写入 Vuex。
|
||
3. 路由跳转 `/chat`；导航守卫检测到 token 后放行。
|
||
4. 聊天页读取用户资料、最近会话，并携带 token 建立 WebSocket。
|
||
5. 最近会话返回后默认打开第一位联系人并拉取最近 10 条消息。
|
||
|
||
### 6.2 发送与接收消息
|
||
|
||
1. 用户点击发送或按 Enter，页面去除首尾空白并检查消息及联系人。
|
||
2. 页面组装 `sendMessage` JSON，通过 WebSocket 发送，并乐观地将消息加入当前视图。
|
||
3. 服务端推送 `newMessage` 时，页面按发送者是否为当前联系人分流：更新当前消息列表，或更新会话预览和未读数。
|
||
4. 页面向服务端发送 `ack`，确认消息已接收。
|
||
|
||
### 6.3 认证失效或退出
|
||
|
||
HTTP 401 会清理认证状态并导航至登录页。用户主动退出会先关闭 WebSocket，再清理 Vuex 状态并返回登录页。当前认证守卫主要检查 token 是否存在，并不验证 token 有效性；有效性最终由服务端响应决定。
|
||
|
||
## 7. 构建与运行配置
|
||
|
||
- `npm install`：安装依赖。
|
||
- `npm run serve`：启动 Vue CLI 开发服务器。
|
||
- `npm run build`：生成生产构建。
|
||
- `npm run lint`：执行 ESLint 检查。
|
||
- 开发环境 `/api` 代理目标为 `http://localhost:3000`。
|
||
- WebSocket URL 在 `src/utils/websocket.js` 中固定为 `ws://localhost:3000`；部署到其他环境前需要配置化，并在 HTTPS 部署时切换到安全 WebSocket (`wss://`)。
|
||
|
||
## 8. 当前边界与改进建议
|
||
|
||
以下内容是根据当前代码观察到的限制，供后续迭代使用，并非已实现功能：
|
||
|
||
1. **运行配置集中化**：HTTP base URL 与 WebSocket 地址目前分散/硬编码，应按开发、测试、生产环境配置，减少部署时遗漏。（已解决）
|
||
2. **认证状态持久性**：token 会持久化，但 username 不持久化；刷新后需由用户信息接口恢复展示状态。还应评估 localStorage 对 token 的安全取舍及 token 过期刷新方案。（username已删除，token问题待解决）
|
||
3. **WebSocket 健壮性**：当前没有断线重连、心跳、待发送队列或连接状态 UI；发送前应明确连接不可用的反馈，并评估 ACK 超时及重复消息处理。
|
||
4. **会话切换与分页状态**：`loadEnd` 等分页标志需要在联系人切换时明确重置；异步消息请求也应避免旧联系人响应覆盖新联系人视图。（已解决）
|
||
5. **实时会话一致性**：收到当前联系人消息时会更新消息区，但当前实现没有同步刷新最近会话预览；接收新消息的未读判断及空会话创建逻辑也值得通过业务用例确认。
|
||
6. **响应契约与错误处理**：页面依赖响应中存在 `data` 字段。建议与服务端定义统一响应 DTO，并区分网络错误、认证错误、业务错误；当前错误主要由页面提示。
|
||
7. **UI 菜单与能力范围**：侧栏存在设置入口，但当前点击后主要改变菜单状态，未形成独立设置页；工具栏的表情和附件按钮也尚未绑定完整功能。
|
||
8. **移动端适配与无障碍**：聊天页最小宽度为 980px；联系人条目以鼠标点击交互为主。若支持移动设备或键盘操作，需补充响应式布局、语义按钮和焦点管理。
|
||
9. **自动化验证**：当前仓库配置了 lint/build 脚本，但未看到专门的单元测试或端到端测试。可优先为认证守卫、消息收发分流、未读计数和历史分页补充测试。 |