pet/utils/sse-usage.md

SSE工具类使用指南

概述

SSE (Server-Sent Events) 工具类提供了通用的流式响应处理功能，支持实时数据流处理、回调机制和错误处理。

主要功能

1. 基础SSE请求 - createSSERequest()

最灵活的底层API，支持完全自定义配置。

import { createSSERequest } from '@/utils/sse.js'

const response = await createSSERequest({
  url: 'https://api.example.com/stream',
  method: 'POST',
  data: { message: '你好' },
  headers: { 'Custom-Header': 'value' },
  onChunk: (chunk) => {
    console.log('接收到数据:', chunk.content)
    console.log('累积内容:', chunk.totalContent)
  },
  onComplete: (result) => {
    console.log('流式响应完成:', result.data)
  },
  onError: (error) => {
    console.error('发生错误:', error)
  },
  doneMarker: '[DONE]' // 自定义结束标记
})

2. 默认配置SSE请求 - createDefaultSSERequest()

带有默认配置的便捷API。

import { createDefaultSSERequest } from '@/utils/sse.js'

const response = await createDefaultSSERequest(
  '/api/chat/stream', // API端点
  { message: '你好' }, // 请求数据
  {
    onChunk: (chunk) => {
      // 处理数据块
      updateUI(chunk.content)
    },
    onComplete: (result) => {
      // 处理完成
      console.log('完成:', result.data.message)
    }
  }
)

3. 宠物助手专用SSE - createPetAssistantSSE()

专门为宠物助手功能设计的API。

import { createPetAssistantSSE } from '@/utils/sse.js'

const response = await createPetAssistantSSE(
  {
    message: '我的宠物生病了怎么办？',
    temperature: 0.7,
    maxTokens: 1000
  },
  {
    onChunk: (chunk) => {
      // 实时更新AI回复
      aiMessage.content = chunk.totalContent
      scrollToBottom()
    },
    onComplete: (result) => {
      // 更新元数据
      aiMessage.isSensitive = result.data.isSensitive
      aiMessage.tokenCount = result.data.tokenCount
    }
  }
)

4. 可取消的SSE请求 - createCancellableSSE()

支持取消操作的SSE请求。

import { createCancellableSSE, SSE_STATUS } from '@/utils/sse.js'

const { promise, cancel, getStatus } = createCancellableSSE({
  url: '/api/stream',
  data: { message: '长时间处理的请求' },
  onChunk: (chunk) => {
    console.log('状态:', getStatus()) // 'streaming'
    updateContent(chunk.content)
  }
})

// 5秒后取消请求
setTimeout(() => {
  if (getStatus() === SSE_STATUS.STREAMING) {
    cancel()
    console.log('请求已取消')
  }
}, 5000)

try {
  const result = await promise
  console.log('请求完成:', result)
} catch (error) {
  console.log('请求被取消或失败:', error)
}

回调函数参数

onChunk(chunk)

• chunk.content - 当前数据块内容
• chunk.totalContent - 累积的完整内容
• chunk.chunk - 原始解析的数据对象

onComplete(result)

• result.data.message - 完整的响应消息
• result.data.isSensitive - 是否包含敏感内容
• result.data.tokenCount - 使用的token数量
• result.data.responseTime - 响应时间

onError(error)

• 网络错误、解析错误或其他异常

状态枚举

import { SSE_STATUS } from '@/utils/sse.js'

SSE_STATUS.PENDING    // 等待中
SSE_STATUS.STREAMING  // 流式传输中
SSE_STATUS.COMPLETED  // 已完成
SSE_STATUS.ERROR      // 发生错误
SSE_STATUS.CANCELLED  // 已取消

在Vue组件中使用

// 在组件中导入
import { createPetAssistantSSE } from '@/utils/sse.js'

export default {
  methods: {
    async sendMessage() {
      // 创建消息对象
      const aiMessage = {
        type: 'ai',
        content: '',
        time: this.getCurrentTime()
      }
      this.messageList.push(aiMessage)
      
      // 发起SSE请求
      try {
        const result = await createPetAssistantSSE(
          { message: this.inputMessage },
          {
            onChunk: (chunk) => {
              // 实时更新内容
              aiMessage.content = chunk.totalContent
              this.$nextTick(() => {
                this.scrollToBottom()
              })
            },
            onComplete: (result) => {
              // 更新元数据
              Object.assign(aiMessage, result.data)
            },
            onError: (error) => {
              console.error('SSE失败:', error)
              // 可以在这里实现降级处理
            }
          }
        )
      } catch (error) {
        // 处理异常
        this.handleError(error)
      }
    }
  }
}

注意事项

1. 自动认证: 工具类会自动添加Authorization头部
2. 错误处理: 建议同时实现onError回调和try-catch
3. 内存管理: 长时间的流式响应注意内存使用
4. 网络状态: 考虑网络中断的情况
5. 降级处理: SSE失败时可以降级到普通API请求

扩展使用

可以基于基础API创建更多专用函数：

// 创建客服聊天SSE
export function createCustomerServiceSSE(data, callbacks) {
  return createDefaultSSERequest('/api/customer/stream', data, callbacks)
}

// 创建代码生成SSE
export function createCodeGenerationSSE(data, callbacks) {
  return createDefaultSSERequest('/api/code/generate', data, callbacks)
}