Vue3 前端生态与全栈应用架构：把经验沉淀成下一次的规则- 惊觉

Vue3 前端生态与全栈应用架构：把经验沉淀成下一次的规则

SSE 组件在切页或取消生成后若不终止连接，可能继续写入已卸载的状态并造成资源泄漏。这是流式交互应覆盖的生命周期场景。

问题复盘应落实为可检查的状态机规则和测试用例，而不是只保留口头提醒。

从线上事故到通用状态机规则

那个 SSE 泄露的故障复盘会开了整整两小时。后来我们意识到，前端处理 LLM 流式响应的复杂程度，远远超出了传统的 REST 接口。

传统的 AJAX 接口只有 Pending -> Fulfilled / Rejected 两种终态。但流式 SSE 涉及 Connecting -> Streaming -> Pausing -> Aborting -> Completed 等多个状态。一旦这些状态分散在各个 .vue 组件的 ref 变量里，逻辑就会乱成一团麻。

为了避免类似问题再次发生，我们把复盘结论硬化成了一套可复用的状态机与清理规则（State Machine Protocol）。

核心原则非常明确：任何流式请求的生命周期，必须与 Vue 组件的 onUnmounted 声明周期形成强绑定。

避坑规则：Vue3 流式响应的三个防护点

根据复盘沉淀出来的经验，前端处理 AI 智能检索与流式交互时，必须遵守以下 3 条工程规则：

1. 强制统一控制 `AbortController`

所有的 SSE 请求必须持有独立的 AbortController 实例。一旦触发组件卸载、页面路由跳转或者用户主动切断，必须在第一时间调用 .abort() 强行打断 Fetch 字节流。

2. 避免高频 Vue 响应式触发

如果每个 Token 到了都直接 streamText.value += token，在模型高速输出时，Vue3 的 Proxy 响应式系统每秒要触发几十上百次微任务调度和 DOM Re-render，导致低端设备严重掉帧。

正确的做法是建立一个缓冲区（Buffer Queue），基于 requestAnimationFrame 批量刷屏更新 UI。

3. 错误状态严格隔离

流式传输中途断网或上游报错，不能简单清空页面。必须保留已经渲染出来的部分回答，并在末尾追加“连接断开”的提示气泡，同时提供一键“从断点继续”的控制按钮。

生产级 Vue3 SSE 状态管理 Composable 实现

下面是基于 Vue3 Composition API + TypeScript 沉淀的通用流式控制 Hook。内置了自动取消、响应式防抖与显式状态机切换：

import { ref, onUnmounted, shallowRef } from 'vue';

export type SSEState = 'IDLE' | 'CONNECTING' | 'STREAMING' | 'ABORTED' | 'ERROR' | 'COMPLETED';

export interface UseSSEReturn {
  state: typeof state;
  content: typeof content;
  errorMessage: typeof errorMessage;
  startStream: (url: string, payload: Record<string, any>) => Promise<void>;
  abortStream: () => void;
}

export function useResilientStream(): UseSSEReturn {
  const state = ref<SSEState>('IDLE');
  const content = ref<string>('');
  const errorMessage = ref<string>('');

  // 使用 shallowRef 保存非响应式的大对象，避免性能开销
  const activeAbortController = shallowRef<AbortController | null>(null);
  
  // 缓冲区与动画帧 Handle
  let tokenBuffer: string[] = [];
  let animFrameId: number | null = null;

  // 批量刷屏逻辑：利用动画帧平滑渲染
  const flushBuffer = () => {
    if (tokenBuffer.length > 0) {
      content.value += tokenBuffer.join('');
      tokenBuffer = [];
    }
    if (state.value === 'STREAMING') {
      animFrameId = requestAnimationFrame(flushBuffer);
    }
  };

  /**
   * 中断当前的流式传输
   */
  const abortStream = () => {
    if (activeAbortController.value) {
      activeAbortController.value.abort();
      activeAbortController.value = null;
    }
    if (animFrameId !== null) {
      cancelAnimationFrame(animFrameId);
      animFrameId = null;
    }
    if (state.value === 'STREAMING' || state.value === 'CONNECTING') {
      state.value = 'ABORTED';
    }
  };

  /**
   * 发起 SSE 流式检索
   */
  const startStream = async (url: string, payload: Record<string, any>) => {
    // 启动前先打断上一次未完成的请求
    abortStream();

    state.value = 'CONNECTING';
    content.value = '';
    errorMessage.value = '';
    
    const controller = new AbortController();
    activeAbortController.value = controller;

    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(payload),
        signal: controller.signal,
      });

      if (!response.ok || !response.body) {
        throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
      }

      state.value = 'STREAMING';
      animFrameId = requestAnimationFrame(flushBuffer);

      const reader = response.body.getReader();
      const decoder = new TextDecoder('utf-8');

      while (true) {
        const { done, value } = await reader.read();
        if (done) {
          state.value = 'COMPLETED';
          break;
        }

        const chunk = decoder.decode(value, { stream: true });
        // 按 SSE 格式按行解析
        const lines = chunk.split('\n');
        for (const line of lines) {
          if (line.startsWith('data: ')) {
            const dataStr = line.slice(6).trim();
            if (dataStr === '[DONE]') {
              state.value = 'COMPLETED';
              break;
            }
            try {
              const parsed = JSON.parse(dataStr);
              if (parsed.delta) {
                tokenBuffer.push(parsed.delta);
              }
            } catch {
              // 容错处理：若非 JSON 则直接推入原始文本
              tokenBuffer.push(dataStr);
            }
          }
        }
      }
    } catch (err: any) {
      if (err.name === 'AbortError') {
        console.log('[SSE] 请求已被用户或系统主动取消');
      } else {
        console.error('[SSE] 流式通信发生异常:', err);
        errorMessage.value = err.message || '网络连接异常';
        state.value = 'ERROR';
      }
    } finally {
      if (animFrameId !== null) {
        cancelAnimationFrame(animFrameId);
        animFrameId = null;
      }
      // 强行刷空剩余缓冲区
      if (tokenBuffer.length > 0) {
        content.value += tokenBuffer.join('');
        tokenBuffer = [];
      }
      activeAbortController.value = null;
    }
  };

  // 关键防护：组件销毁时自动强行切断连接，防止内存泄漏
  onUnmounted(() => {
    abortStream();
  });

  return {
    state,
    content,
    errorMessage,
    startStream,
    abortStream,
  };
}

团队架构沉淀的三原则

把每次线上故障的复盘整理成可执行的代码模版，比写十篇理论文档都有用。在 Vue3 全栈架构演进中，我们坚持了三条铁律：

所有的副作用必须有解绑归宿：无论是事件监听、定时器，还是 SSE 流，在 Hook 或组件销毁时必须同步清理。
分离渲染逻辑与传输逻辑：打字机渲染不要侵入 UI 组件内部，交给专门的 Composable 维护状态机。
建立项目规范门禁：在代码审查（CR）清单里增加一条强制项——“检查所有 fetch 接口是否具备 AbortController 绑定”。

复盘记录不应该躺在文档库里发霉，把痛踩过的坑转化成确定性的工程架构约束，团队的开发效率和稳定性自然就上去了。

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/qq_34803115/article/details/163804351

Vue3 前端生态与全栈应用架构：把经验沉淀成下一次的规则