/** * SSE 客户端封装。 * * ## 为什么用 fetch 而不是浏览器原生 EventSource * * 文档最初设想用 EventSource,但 EventSource 有两个无法绕开的限制: * * 1. **不能自定义请求头**。它无法携带 `Authorization: Bearer`, * 只能靠 URL query 传 token,而 URL 会进入 nginx access log、 * 浏览器历史与 Referer,是实打实的凭据泄露面。 * 2. **无法主动中断**。只有 `close()`,无法区分「用户点了停止」和 * 「网络断开」,也拿不到 HTTP 状态码与错误响应体 —— 后端返回的 * 「Ollama 未启动」这类有价值提示会被静默吞掉。 * * `fetch` + `ReadableStream` 手动解析 SSE 能同时解决这两点, * 且服务端协议完全不变(依然是 `text/event-stream` + `event:`/`data:` 帧), * 后端不需要为前端实现方式做任何妥协。 * * 若你确实需要用原生 EventSource,见文件末尾的 `streamChatViaEventSource`。 */ const SSE_DATA_PREFIX = 'data:' const SSE_EVENT_PREFIX = 'event:' /** * 建立 SSE 连接并流式消费事件。 * * @param {object} options * @param {string} options.url 请求地址(相对 /api 路径) * @param {string} options.token JWT,放入 Authorization 头 * @param {(event: string, data: object) => void} options.onEvent 事件回调 * @param {(error: Error) => void} [options.onError] 错误回调 * @param {() => void} [options.onClose] 流正常结束回调 * @returns {{ abort: () => void }} 控制器,调用 abort() 中断连接 */ export function streamChat({ url, token, onEvent, onError, onClose }) { const controller = new AbortController() // 用户主动中断的标志:用于在 catch 里区分「主动停止」与「真的出错」 let abortedByUser = false /** * 终止回调只允许触发一次。 * * 这是修一个真实 bug 的关键:`abort()` 主动中断时,`reader.read()` 是否 * 会 reject 一个 AbortError 在不同浏览器/不同时刻表现并不一致 —— * 有时它只是安静地返回 { done: true },于是 onClose 永远不触发, * 调用方的 `streaming` 标志就卡在 true:发送按钮**永久变灰**, * 必须刷新页面才能恢复。 * * 因此不再依赖「异常是否抛出」来决定收尾,而是显式收口: * abort() 立即结算,流自然结束也结算,谁先到算谁,只结算一次。 */ let settled = false const settle = (fn) => { if (settled) return settled = true fn?.() } const run = async () => { let response try { response = await fetch(url, { method: 'GET', headers: { Accept: 'text/event-stream', Authorization: `Bearer ${token}` }, signal: controller.signal, // 不使用 Cookie 认证,避免 CSRF 面 credentials: 'omit' }) } catch (err) { // 主动中断由 abort() 负责结算,这里直接返回,避免重复回调 if (abortedByUser || err.name === 'AbortError') { return } settle(() => onError?.(new Error('无法建立连接,请确认后端服务已启动'))) return } // 后端在流开始前返回错误(如 401、404、400),此时是普通 JSON 响应 if (!response.ok) { let message = `请求失败 (HTTP ${response.status})` try { const body = await response.json() if (body?.msg) message = body.msg } catch { // 响应体不是 JSON,沿用默认提示 } settle(() => onError?.(new Error(message))) return } if (!response.body) { settle(() => onError?.(new Error('当前浏览器不支持流式响应(ReadableStream 不可用)'))) return } const reader = response.body.getReader() const decoder = new TextDecoder('utf-8') // 跨 chunk 的残留数据:一个 SSE 帧可能被 TCP 分片切开 let buffer = '' try { while (true) { const { done, value } = await reader.read() if (done) break buffer += decoder.decode(value, { stream: true }) // SSE 帧以空行分隔。把完整帧逐个取出来处理,剩余部分留回 buffer。 let separatorIndex while ((separatorIndex = findFrameEnd(buffer)) !== -1) { const rawFrame = buffer.slice(0, separatorIndex) buffer = buffer.slice(separatorIndex).replace(/^(\r?\n){2}/, '') handleFrame(rawFrame, onEvent) } } // 处理最后一个可能没有以空行结尾的帧 if (buffer.trim()) { handleFrame(buffer, onEvent) } settle(onClose) } catch (err) { // 主动中断已由 abort() 结算,这里静默返回 if (abortedByUser || err.name === 'AbortError') { return } settle(() => onError?.(new Error(`读取流数据失败: ${err.message}`))) } finally { try { reader.releaseLock() } catch { // 流已关闭,忽略 } } } run() return { abort() { abortedByUser = true // 先中断网络请求,再立即结算 —— 不等待 reader.read() 抛错, // 否则异常语义在浏览器间不一致时会漏掉收尾,导致 loading 卡死 controller.abort() settle(onClose) } } } /** * 找到第一个完整 SSE 帧的结束位置。 * * 兼容 `\n\n` 与 `\r\n\r\n` 两种换行风格 —— * 不同代理(nginx / 某些网关)会改写换行符。 */ function findFrameEnd(text) { const lf = text.indexOf('\n\n') const crlf = text.indexOf('\r\n\r\n') if (lf === -1) return crlf if (crlf === -1) return lf return Math.min(lf, crlf) } /** * 解析单个 SSE 帧并触发回调。 * * 帧格式: * event: delta * data: {"type":"delta","delta":"你"} * * 以 `:` 开头的行是注释(常用于心跳),直接忽略。 */ function handleFrame(rawFrame, onEvent) { let eventName = 'message' const dataLines = [] for (const line of rawFrame.split(/\r?\n/)) { if (!line || line.startsWith(':')) continue if (line.startsWith(SSE_EVENT_PREFIX)) { eventName = line.slice(SSE_EVENT_PREFIX.length).trim() } else if (line.startsWith(SSE_DATA_PREFIX)) { // 去掉前缀后的一个空格(规范允许 `data:foo` 与 `data: foo`) dataLines.push(line.slice(SSE_DATA_PREFIX.length).replace(/^ /, '')) } } if (dataLines.length === 0) return const payload = dataLines.join('\n') let parsed try { parsed = JSON.parse(payload) } catch { // 非 JSON 载荷(理论上本项目的后端不会这样发)按纯文本处理 parsed = { type: eventName, delta: payload } } onEvent?.(eventName, parsed) } /** * 原生 EventSource 备用实现。 * * **仅在你愿意接受 token 出现在 URL 中时使用。** * 服务端已支持 `?token=` 认证(见 JwtAuthenticationFilter), * 因此这个实现在功能上可用,但请务必: * - 生产环境通过 nginx 关闭该路径 query 的日志记录 * - 强制 HTTPS,避免 token 明文传输 * * @param {object} options * @param {string} options.baseUrl 后端地址,如 'http://localhost:8080' * @param {number} options.chatId * @param {string} options.token * @param {object} options.params query 参数:content/parentId/model/useRag * @param {(event: string, data: object) => void} options.onEvent * @param {(error: Error) => void} [options.onError] */ export function streamChatViaEventSource({ baseUrl = '', chatId, token, params, onEvent, onError }) { const query = new URLSearchParams({ ...params, token }) const url = `${baseUrl}/api/chats/${chatId}/stream?${query.toString()}` const source = new EventSource(url) // 逐个注册后端约定的事件类型。 // EventSource 不提供「监听所有事件」的能力,必须显式列出。 for (const eventName of ['start', 'delta', 'title', 'done', 'error']) { source.addEventListener(eventName, (event) => { try { onEvent?.(eventName, JSON.parse(event.data)) } catch (err) { onError?.(new Error(`解析 ${eventName} 事件失败: ${err.message}`)) } // done / error 之后流已结束,主动关闭以释放后端 SseEmitter if (eventName === 'done' || eventName === 'error') { source.close() } }) } source.onerror = () => { // EventSource 会自动重连,但对话流不该重连(会重复生成)。 // 因此这里直接关闭并把控制权交给上层。 source.close() onError?.(new Error('SSE 连接中断')) } return { abort() { source.close() } } }