Mirage Flow赋能Vue前端开发智能对话界面的完整实践最近在做一个技术问答平台的前端核心需求是要集成一个智能对话助手。用户可以在页面上直接提问然后像和真人聊天一样看到助手一个字一个字“打”出来的回答。听起来简单但真做起来从建立稳定的长连接到处理流式数据再到管理复杂的对话状态每一步都挺有挑战。我们最终选择了 Mirage Flow 作为后端服务它提供了稳定、高效的流式对话接口。这篇文章我就来聊聊我们团队是如何在 Vue.js 项目中一步步把 Mirage Flow 的能力“搬”到前端的。我会重点分享那些在工程实践中踩过的坑和总结出的最佳实践希望能帮你少走弯路。1. 项目蓝图我们想构建什么样的对话体验在动手写代码之前我们得先想清楚最终要给用户一个什么样的产品。这决定了我们前端架构的设计方向。我们的目标是构建一个在线技术问答平台的智能助手模块。用户在前端页面输入技术问题比如“如何在 Vue 3 中使用 Composition API 管理全局状态”然后助手会以流式响应的方式逐步给出详细、专业的解答。基于这个目标我们梳理出了几个核心的前端需求实时双向通信对话必须是实时的用户发送消息后能立刻得到响应并且响应内容要像打字一样流式呈现而不是等全部生成完再一次性显示。对话上下文管理助手需要记住当前对话的历史这样在连续提问时才能保持连贯性。前端需要妥善存储和管理这些历史消息。良好的用户体验包括发送状态提示如“正在思考…”、响应过程中的加载动画、错误处理如网络中断友好提示以及清晰的消息排版。工程化的前端架构代码要易于维护、扩展和测试。这意味着我们需要将网络通信、状态管理、UI渲染逻辑清晰地分离。基于这些需求我们设计了前后端分离的架构。后端Mirage Flow专注于模型推理和流式数据生成前端Vue.js则负责所有用户交互、数据展示和状态管理两者通过 WebSocket 协议进行高效、实时的数据交换。2. 搭建基石Vue项目初始化与核心依赖工欲善其事必先利其器。我们从一个标准的 Vue 3 项目开始并引入几个关键的库来构建我们的对话系统。我们使用 Vite 和 TypeScript 来创建项目这能为我们提供更快的开发体验和更好的类型安全。# 创建项目 npm create vuelatest vue-mirage-chat # 按照提示选择 TypeScript、Router、Pinia 等选项 # 进入项目并安装核心依赖 cd vue-mirage-chat npm install除了 Vue 生态的核心库Vue Router, Pinia我们还需要专门处理 WebSocket 连接和 UI 组件。# 安装项目所需依赖 npm install axios pinia-plugin-persistedstate # 注意我们选择浏览器原生 WebSocket因其足够轻量且可控无需额外安装库。这里解释一下我们的选择Pinia这是 Vue 的官方状态管理库。我们将用它来集中管理对话历史、连接状态等全局数据让各个组件都能方便地访问和修改。pinia-plugin-persistedstate这个插件能让 Pinia 的状态持久化存储在浏览器的 localStorage 中。这样即使用户刷新页面之前的对话记录也不会丢失。原生 WebSocket对于这种需要精细控制连接生命周期、重连逻辑和消息格式的场景直接使用浏览器提供的WebSocketAPI 反而更灵活、更轻量。我们会在业务层对它进行封装。项目创建好后我们在src/stores目录下初始化 Pinia store并在main.ts中启用持久化插件为后续的状态管理做好准备。3. 建立通道封装稳定可靠的WebSocket服务与 Mirage Flow 后端通信的核心是 WebSocket。一个健壮的 WebSocket 服务封装是整个应用稳定的关键。我们不能直接用new WebSocket()然后到处写回调那样代码会很难维护。我们在src/services目录下创建一个websocket.service.ts文件目标是封装一个具有自动重连、心跳检测、消息队列等能力的 WebSocket 客户端。// src/services/websocket.service.ts import { ref } from vue; export interface WSMessage { type: query | cancel | heartbeat; data: any; } class WebSocketService { private socket: WebSocket | null null; private reconnectAttempts 0; private maxReconnectAttempts 5; private heartbeatInterval: number | null null; private messageQueue: WSMessage[] []; // 消息队列用于连接建立前缓存消息 public isConnected ref(false); // 事件回调函数 public onMessage: ((event: MessageEvent) void) | null null; public onError: ((event: Event) void) | null null; public onOpen: (() void) | null null; public onClose: (() void) | null null; constructor(private url: string) {} connect(): void { try { this.socket new WebSocket(this.url); this.setupEventListeners(); } catch (error) { console.error(WebSocket 连接失败:, error); this.handleReconnect(); } } private setupEventListeners(): void { if (!this.socket) return; this.socket.onopen () { console.log(WebSocket 连接已建立); this.isConnected.value true; this.reconnectAttempts 0; // 重置重连计数 this.startHeartbeat(); this.flushMessageQueue(); // 连接建立后发送缓存的消息 if (this.onOpen) this.onOpen(); }; this.socket.onmessage (event) { // 过滤心跳响应 if (event.data pong) return; if (this.onMessage) this.onMessage(event); }; this.socket.onerror (event) { console.error(WebSocket 错误:, event); if (this.onError) this.onError(event); }; this.socket.onclose (event) { console.log(WebSocket 连接关闭代码: ${event.code}); this.isConnected.value false; this.stopHeartbeat(); if (!event.wasClean this.reconnectAttempts this.maxReconnectAttempts) { this.handleReconnect(); } if (this.onClose) this.onClose(); }; } send(message: WSMessage): void { // 如果连接未就绪将消息加入队列 if (!this.socket || this.socket.readyState ! WebSocket.OPEN) { this.messageQueue.push(message); return; } try { this.socket.send(JSON.stringify(message)); } catch (error) { console.error(发送消息失败:, error); } } private flushMessageQueue(): void { while (this.messageQueue.length 0) { const msg this.messageQueue.shift(); if (msg) this.send(msg); } } private startHeartbeat(): void { this.heartbeatInterval window.setInterval(() { if (this.socket?.readyState WebSocket.OPEN) { this.send({ type: heartbeat, data: {} }); } }, 30000); // 每30秒发送一次心跳 } private stopHeartbeat(): void { if (this.heartbeatInterval) { clearInterval(this.heartbeatInterval); this.heartbeatInterval null; } } private handleReconnect(): void { if (this.reconnectAttempts this.maxReconnectAttempts) { console.error(已达到最大重连次数放弃连接。); return; } this.reconnectAttempts; const delay Math.min(1000 * 2 ** this.reconnectAttempts, 30000); // 指数退避 console.log(${delay}ms后尝试第${this.reconnectAttempts}次重连...); setTimeout(() this.connect(), delay); } disconnect(): void { this.stopHeartbeat(); this.messageQueue []; if (this.socket) { this.socket.close(1000, 用户主动断开); this.socket null; } } } // 导出单例确保全局只有一个连接实例 export const wsService new WebSocketService(ws://your-mirage-flow-server/chat); // 替换为你的实际地址这个服务类处理了连接的生命周期、异常重连、心跳保活和消息缓存为上层业务提供了一个稳定可靠的通信基础。4. 管理状态用Pinia构建对话数据中心前端应用的状态管理至关重要。我们使用 Pinia 来创建一个集中式的 store管理所有与对话相关的状态包括消息列表、当前连接状态等。在src/stores目录下创建chat.store.ts// src/stores/chat.store.ts import { defineStore } from pinia; import { ref, computed } from vue; import { wsService } from /services/websocket.service; export interface ChatMessage { id: string; role: user | assistant; content: string; timestamp: number; isStreaming?: boolean; // 标记是否正在流式输出 } export const useChatStore defineStore(chat, () { // 状态 const messages refChatMessage[]([]); const currentInput ref(); const isLoading ref(false); const connectionStatus refconnecting | connected | disconnected(disconnected); // 计算属性 const reversedMessages computed(() [...messages.value].reverse()); // 用于界面展示最新消息在底部 // 初始化时连接WebSocket并监听事件 const initWebSocket () { wsService.onOpen () { connectionStatus.value connected; }; wsService.onClose () { connectionStatus.value disconnected; }; wsService.onError () { connectionStatus.value disconnected; }; wsService.onMessage handleIncomingMessage; wsService.connect(); }; // 处理接收到的消息 const handleIncomingMessage (event: MessageEvent) { try { const data JSON.parse(event.data); // 假设Mirage Flow返回的数据格式为 { type: chunk | end, content: string, messageId?: string } if (data.type chunk) { // 流式数据块 appendToAssistantMessage(data.content); } else if (data.type end) { // 流式结束 finalizeAssistantMessage(); isLoading.value false; } } catch (error) { console.error(解析消息失败:, error, event.data); } }; // 追加内容到最后一条助手消息或创建新消息 const appendToAssistantMessage (contentChunk: string) { const lastMsg messages.value[messages.value.length - 1]; if (lastMsg lastMsg.role assistant lastMsg.isStreaming) { // 追加到正在流式输出的消息 lastMsg.content contentChunk; } else { // 创建新的助手消息 const newMsg: ChatMessage { id: msg_${Date.now()}, role: assistant, content: contentChunk, timestamp: Date.now(), isStreaming: true, }; messages.value.push(newMsg); } }; const finalizeAssistantMessage () { const lastMsg messages.value[messages.value.length - 1]; if (lastMsg lastMsg.role assistant) { lastMsg.isStreaming false; } }; // 发送用户消息 const sendMessage async () { const userMessage currentInput.value.trim(); if (!userMessage || isLoading.value || !wsService.isConnected.value) return; // 添加用户消息到列表 const userMsg: ChatMessage { id: msg_${Date.now()}, role: user, content: userMessage, timestamp: Date.now(), }; messages.value.push(userMsg); currentInput.value ; isLoading.value true; // 通过WebSocket发送消息 wsService.send({ type: query, data: { message: userMessage, history: messages.value.slice(-6).map(m ({ role: m.role, content: m.content })), // 发送最近几条作为上下文 }, }); }; // 清空对话 const clearMessages () { messages.value []; }; // 断开连接 const disconnect () { wsService.disconnect(); connectionStatus.value disconnected; }; return { messages, currentInput, isLoading, connectionStatus, reversedMessages, initWebSocket, sendMessage, clearMessages, disconnect, }; }, { persist: true, // 启用持久化对话历史将保存在 localStorage });这个 Store 将消息列表、输入框状态、加载状态以及所有与对话相关的操作都集中管理起来。通过persist插件用户的对话历史在刷新页面后依然存在体验更连贯。5. 构建界面Vue组件与流式渲染有了稳定的通信和清晰的状态管理接下来就是构建用户界面了。我们创建一个ChatWindow.vue组件。这个组件的核心任务有两个一是清晰展示对话历史二是提供便捷的输入交互。其中流式渲染是体验的关键我们需要让助手消息的内容能够逐字实时更新。!-- src/components/ChatWindow.vue -- template div classchat-container !-- 连接状态指示器 -- div classstatus-bar span :class[status-dot, connectionStatus]/span span classstatus-text {{ statusText }} /span button v-ifconnectionStatus connected clickhandleDisconnect classbtn-disconnect 断开连接 /button /div !-- 消息列表区域 -- div refmessagesContainer classmessages-container div v-ifstore.messages.length 0 classempty-placeholder p欢迎使用技术问答助手请在下方的输入框中提出你的问题。/p /div div v-else div v-formsg in store.reversedMessages :keymsg.id :class[message-bubble, msg.role] div classmessage-avatar {{ msg.role user ? 你 : AI }} /div div classmessage-content !-- 使用 v-html 渲染 Markdown (生产环境需做XSS过滤) -- !-- 对于流式消息内容会动态更新 -- div v-ifmsg.role assistant msg.isStreaming classstreaming-content {{ msg.content }} span classstreaming-cursor/span /div div v-else v-htmlrenderMarkdown(msg.content)/div div classmessage-time {{ formatTime(msg.timestamp) }} /div /div /div !-- 加载指示器 -- div v-ifstore.isLoading classthinking-indicator span助手正在思考/span span classdot-flashing/span /div /div /div !-- 输入区域 -- div classinput-area textarea v-modelstore.currentInput keydown.enter.exact.preventhandleSend placeholder输入技术问题按 Enter 发送ShiftEnter 换行... rows3 :disabledstore.isLoading || store.connectionStatus ! connected /textarea div classinput-actions button clickstore.sendMessage :disabled!canSend classbtn-send 发送 /button button clickstore.clearMessages classbtn-clear 清空对话 /button /div /div /div /template script setup langts import { computed, nextTick, ref, onMounted, onUnmounted } from vue; import { useChatStore } from /stores/chat.store; import { renderMarkdown } from /utils/markdownRenderer; // 一个简单的Markdown转HTML函数 import { formatTime } from /utils/dateFormatter; const store useChatStore(); const messagesContainer refHTMLElement(); // 计算发送按钮是否可用 const canSend computed(() { return ( store.currentInput.trim().length 0 !store.isLoading store.connectionStatus connected ); }); // 状态显示文本 const statusText computed(() { const map { connecting: 连接中..., connected: 已连接, disconnected: 已断开, }; return map[store.connectionStatus]; }); // 发送消息处理支持键盘快捷键 const handleSend () { if (canSend.value) { store.sendMessage(); } }; // 断开连接 const handleDisconnect () { store.disconnect(); }; // 当有新消息或流式内容更新时自动滚动到底部 const scrollToBottom () { nextTick(() { if (messagesContainer.value) { messagesContainer.value.scrollTop messagesContainer.value.scrollHeight; } }); }; // 监听消息列表和加载状态的变化触发滚动 watch(() [...store.messages, store.isLoading], scrollToBottom, { deep: true }); // 组件挂载时初始化WebSocket连接 onMounted(() { store.initWebSocket(); }); // 组件卸载时清理可根据需要决定是否断开 onUnmounted(() { // store.disconnect(); // 如果希望单页应用内保持连接可以不调用 }); /script style scoped /* 这里省略具体的CSS样式但会包含 - 消息气泡样式区分用户和助手 - 流式光标动画 - 加载指示器动画 - 输入框和按钮样式 - 滚动区域样式 */ /style这个组件实现了完整的对话界面。当助手消息的isStreaming为true时我们会同时渲染一个闪烁的光标动画模拟打字效果。通过监听messages的变化并自动滚动确保了用户总能看见最新的消息。6. 效果与思考从实现到优化把上面这些部分组合起来一个功能完整的智能对话前端就基本成型了。用户打开页面自动连接服务输入问题就能看到流式的回答对话历史也会被保存下来。实际跑起来效果还是挺令人满意的。流式响应让等待过程变得不那么枯燥用户体验比一次性等待整个响应要好很多。Pinia 的状态管理也让代码结构非常清晰新增功能或者调试问题都更方便。当然在实际开发中我们还遇到并解决了一些具体问题消息格式对齐确保前端发送的消息格式与 Mirage Flow 后端接口期望的格式完全一致。我们定义了一个清晰的协议包括消息类型query,cancel,heartbeat和数据结构。错误处理与用户提示网络不稳定、服务端错误、用户主动取消等情况都需要考虑。我们增加了相应的 UI 提示和重试机制。性能考量当对话历史非常长时直接全部渲染和传递给后端都可能成为瓶颈。我们前端做了虚拟滚动对于超长列表并且传递给后端的上下文历史也做了长度限制。安全性示例中直接使用v-html渲染 Markdown在实际生产环境必须对内容进行严格的消毒Sanitize防止 XSS 攻击。这套架构的好处是清晰和灵活。WebSocket 服务、状态管理、UI 组件各司其职。如果你想更换 UI 库比如用 Element Plus 或 Naive UI或者想适配另一个提供类似流式接口的 AI 服务只需要修改对应的部分即可核心的通信和状态逻辑可以复用。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。