参数	说明	类型	默认值
url	连接地址（必填）	string	-
eventListeners	后端自定义消息类型的监听器配置	object	{}
parseMessage	是否自动解析消息	boolean	false
reconnectTime	重连间隔（毫秒）	number	60000
retryCount	重试次数，设置为 0 可禁用自动重连	number	5
streamTimeout	流式响应超时（毫秒），设置为 0 可禁用超时检测	number	300000
withCredentials	是否发送凭证	boolean	false
debugger	是否开启调试日志	boolean	true
autoReconnect	是否启用自动重连	boolean	true
timeout	连接建立超时时间（毫秒）	number	5000

配置禁用说明：

禁用流式响应超时

const aiChat = new WSSE({
  url: "https://api.ai-service.com/stream",
  streamTimeout: 0  // 设置为0即可禁用流式响应超时
});

禁用自动重连

const aiChat = new WSSE({
  url: "https://api.ai-service.com/stream",
  autoReconnect: false,  // 方式1：直接禁用自动重连
  retryCount: 0          // 方式2：设置重试次数为0
});

基础用法

import WSSE from 'wsse-sdk';

const aiChat = new WSSE({
  url: "https://api.ai-service.com/stream",
  // 配置后端自定义消息类型的监听器
  eventListeners: {
    chat_response: (data) => {
      console.log('收到聊天响应:', data);
    },
    error_message: (data) => {
      console.log('收到错误消息:', data);
    }
  },
  parseMessage: true,                // 启用消息自动解析（默认关闭）
  streamTimeout: 300000,             // 流式响应5分钟超时
});

// 添加系统事件监听
aiChat.on({
  // 连接建立时触发
  open: () => console.log('连接已建立'),
  
  // 连接错误时触发
  error: (error) => console.error('连接错误:', error),

  // 默认消息处理器，处理所有未指定类型的消息
  message: (event) => {
    const data = JSON.parse(event.data);
    console.log('收到未指定类型的消息:', data);
    
    // 根据消息类型做不同处理
    switch(data.type) {
      case 'stream':
        console.log('流式响应片段:', data.content);
        break;
      case 'done':
        console.log('响应结束');
        break;
      default:
        console.log('其他类型消息:', data);
    }
  }
});

// 添加额外的自定义消息类型监听
aiChat.addMessageListener({
  status_update: (data) => {
    console.log('状态更新:', data);
  }
});

// 手动重连
await aiChat.reconnect();

// 关闭连接
aiChat.close();

消息处理

传递参数示例

import WSSE from 'wsse-sdk';

// 1. URL 参数方式
const aiChat1 = new WSSE({
  url: "https://api.ai-service.com/stream?userId=123&token=abc",
  eventListeners: {
    chat_response: (data) => console.log('收到响应:', data)
  }
});

// 2. URL 路径参数方式
const aiChat2 = new WSSE({
  url: "https://api.ai-service.com/stream/user/123",
  eventListeners: {
    chat_response: (data) => console.log('收到响应:', data)
  }
});

// 3. 跨域携带凭证方式
const aiChat3 = new WSSE({
  url: "https://api.ai-service.com/stream",
  withCredentials: true,  // 允许跨域请求携带 cookie
  eventListeners: {
    chat_response: (data) => console.log('收到响应:', data)
  }
});

// 4. 动态更新连接
let connectionUrl = "https://api.ai-service.com/stream";
const token = "user-token";

// 添加认证信息
const addAuthToUrl = (baseUrl, token) => {
  const url = new URL(baseUrl);
  url.searchParams.append('token', token);
  return url.toString();
}

const aiChat4 = new WSSE({
  url: addAuthToUrl(connectionUrl, token),
  eventListeners: {
    chat_response: (data) => console.log('收到响应:', data)
  }
});

📖 高级功能

自动解析消息

SDK 默认不会自动解析消息，需要通过 parseMessage 配置项来开启。这样可以让用户更灵活地控制消息解析方式。

配置说明

// 手动解析消息（默认行为）
const aiChat = new WSSE({
  url: "https://api.ai-service.com/stream",
  eventListeners: {
    chat_response: (event) => {
      // 需要手动解析消息
      const data = JSON.parse(event.data);
      console.log('收到聊天响应:', data);
    }
  }
});

// 开启自动解析
const aiChatWithParse = new WSSE({
  url: "https://api.ai-service.com/stream",
  parseMessage: true,  // 开启自动解析
  eventListeners: {
    chat_response: (data) => {
      // data 已经是解析后的对象
      console.log('收到聊天响应:', data);
    }
  }
});

解析规则

自动解析开启 (parseMessage: true)

// 后端发送的原始消息
event.data = '{"type":"chat_response","content":"Hello","timestamp":1678234567890}'

// 监听器收到的数据（自动解析为对象）
{
  type: "chat_response",
  content: "Hello",
  timestamp: 1678234567890
}

自动解析关闭 (parseMessage: false)

// 监听器收到的是原始字符串
aiChat.on({
  message: (event) => {
    // 需要手动解析
    const data = JSON.parse(event.data);
    console.log(data);
  }
});

错误处理

解析失败处理

aiChat.on({
  message: (event) => {
    try {
      // 手动解析示例
      const data = parseMessage ? JSON.parse(event.data) : event.data;
      console.log('解析成功:', data);
    } catch (error) {
      console.error('消息解析失败:', error);
      // 保留原始数据
      console.log('原始数据:', event.data);
    }
  }
});

特殊格式处理

const aiChat = new WSSE({
  url: "https://api.ai-service.com/stream",
  parseMessage: true,
  eventListeners: {
    chat_response: (event) => {
      // 某些情况下可能需要特殊处理
      const rawData = event.data;
      let data;
      
      // 处理特殊格式
      if (rawData.startsWith('data: ')) {
        data = JSON.parse(rawData.slice(6));
      } else {
        data = JSON.parse(rawData);
      }
      
      console.log('处理后的数据:', data);
    }
  }
});

最佳实践

标准 JSON 格式

// 推荐的消息格式
{
  "type": "chat_response",      // 消息类型（必需）
  "content": "消息内容",        // 消息内容
  "timestamp": 1678234567890,   // 时间戳
  "metadata": {                 // 额外信息（可选）
    "messageId": "abc123",
    "status": "success"
  }
}

非标准格式处理

const aiChat = new WSSE({
  url: "https://api.ai-service.com/stream",
  parseMessage: false,  // 关闭自动解析
  eventListeners: {
    chat_response: (event) => {
      // 自定义解析逻辑
      const data = customParser(event.data);
      console.log('自定义解析结果:', data);
    }
  }
});

function customParser(rawData) {
  // 实现自定义解析逻辑
  // 返回解析后的数据
}

流式内容管理

获取当前流式内容

const aiChat = new WSSE({
  url: "https://api.ai-service.com/stream",
  eventListeners: {
    // 监听流式内容完成事件
    streamComplete: (content) => {
      console.log('完整的流式内容:', content);
    },
    // 监听消息入队事件
    messageQueued: (message) => {
      console.log('新消息已入队:', message);
    }
  }
});

错误处理最佳实践

const aiChat = new WSSE({
  url: "https://api.ai-service.com/stream",
  retryCount: 3,
  reconnectTime: 5000,
  eventListeners: {
    error_message: (error) => {
      switch(error.code) {
        case 'TOKEN_EXPIRED':
          // 处理 token 过期
          refreshToken().then(() => aiChat.reconnect());
          break;
        case 'RATE_LIMIT':
          // 处理限流
          console.warn('请求过于频繁，请稍后重试');
          break;
        default:
          // 其他错误处理
          console.error('发生错误:', error);
      }
    }
  }
});

// 手动重连时的错误处理
try {
  await aiChat.reconnect();
  console.log('重连成功');
} catch (error) {
  console.error('重连失败:', error);
}

状态管理

1. 消息过滤和转换

const aiChat = new WSSE({
  url: "https://api.ai-service.com/stream",
  eventListeners: {
    chat_response: (message) => {
      // 过滤特定类型的消息
      if (message.type === 'thought') {
        return; // 忽略思考过程
      }
      
      // 转换消息格式
      const transformedMessage = {
        content: message.content,
        timestamp: Date.now(),
        formatted: true
      };
      
      console.log('处理后的消息:', transformedMessage);
    }
  }
});

2. 连接状态管理

const aiChat = new WSSE({
  url: "https://api.ai-service.com/stream"
});

// 监听连接状态变化
aiChat.on({
  open: () => {
    console.log('连接状态:', aiChat.state); // WSSE.STATE_OPEN
    console.log('是否正在重连:', aiChat.isReconnecting);
    console.log('是否正在连接:', aiChat.isConnecting);
  }
});

// 状态常量
console.log('连接中:', WSSE.STATE_CONNECTING);    // 0
console.log('已连接:', WSSE.STATE_OPEN);          // 1
console.log('已关闭:', WSSE.STATE_CLOSED);        // 2

连接管理注意事项

流式响应
- 设置了5分钟的默认超时时间
- 超时后会触发 streamTimeout 事件
自动重连
- 连接断开后自动重试
- 可配置重试次数和间隔时间
消息类型监听
- eventListeners 用于配置后端自定义的消息类型监听器
- on 方法用于监听系统事件（如 open、error）
- addMessageListener 用于动态添加自定义消息类型监听器

性能优化建议

重连策略优化
- 根据实际需求设置 retryCount
- 避免过于频繁的重连尝试
内存管理
- 及时调用 close() 释放资源
- 清理不需要的消息监听器

⚠️ 使用注意事项

参数传递注意事项

URL 参数传递

// 推荐：构建 URL 时使用 URLSearchParams
const params = new URLSearchParams({
  userId: '123',
  token: 'abc',
  timestamp: Date.now()
});

const aiChat = new WSSE({
  url: `https://api.ai-service.com/stream?${params.toString()}`
});

认证信息传递

// 方式1：通过 URL 参数
const aiChat1 = new WSSE({
  url: "https://api.ai-service.com/stream?token=abc"
});

// 方式2：通过 cookie（需要后端支持）
const aiChat2 = new WSSE({
  url: "https://api.ai-service.com/stream",
  withCredentials: true  // 允许跨域请求携带 cookie
});

动态参数处理

class ChatService {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
    this.sseInstance = null;
  }

  connect(params = {}) {
    // 构建URL
    const url = new URL(this.baseUrl);
    Object.entries(params).forEach(([key, value]) => {
      url.searchParams.append(key, value);
    });

    // 创建SSE实例
    this.sseInstance = new WSSE({
      url: url.toString(),
      eventListeners: {
        chat_response: this.handleResponse.bind(this)
      }
    });
  }

  handleResponse(data) {
    console.log('收到响应:', data);
  }

  disconnect() {
    this.sseInstance?.close();
  }
}

// 使用示例
const chatService = new ChatService('https://api.ai-service.com/stream');
chatService.connect({
  userId: '123',
  token: 'abc',
  timestamp: Date.now()
});

连接管理注意事项

流式响应
- 设置了5分钟的默认超时时间
- 超时后会触发 streamTimeout 事件
自动重连
- 连接断开后自动重试
- 可配置重试次数和间隔时间
消息类型监听
- eventListeners 用于配置后端自定义的消息类型监听器
- on 方法用于监听系统事件（如 open、error）
- addMessageListener 用于动态添加自定义消息类型监听器
消息处理
- 后端发送的消息需要指定 type 字段
- type 字段值需要与监听器配置的键名一致

性能优化建议

重连策略优化
- 根据实际需求设置 retryCount
- 避免过于频繁的重连尝试
内存管理
- 及时调用 close() 释放资源
- 清理不需要的消息监听器

📱 系统要求

浏览器兼容性

Chrome 92+
Firefox 90+
Safari 14.1+
Edge 92+

📄 许可证

MIT

FAQs

What is wsse-sdk?

Is wsse-sdk well maintained?

Package last updated on 14 Mar 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

wsse-sdk

WSSE-SDK

✨ 特性

📦 安装

🚀 快速开始

基础配置项

基础用法

消息处理

传递参数示例

📖 高级功能

自动解析消息

配置说明

解析规则

错误处理

最佳实践

流式内容管理

获取当前流式内容

错误处理最佳实践

状态管理

1. 消息过滤和转换

2. 连接状态管理

连接管理注意事项

性能优化建议

⚠️ 使用注意事项

参数传递注意事项

连接管理注意事项

性能优化建议

📱 系统要求

浏览器兼容性

📄 许可证

Related posts

Axios Maintainer Confirms Social Engineering Attack Behind npm Compromise

Node.js Drops Bug Bounty Rewards After Funding Dries Up