sse.js 使用与安装指南

sse.js 使用与安装指南

【免费下载链接】sse.js A flexible Server-Sent Events EventSource polyfill for Javascript 项目地址: https://gitcode.com/gh_mirrors/ss/sse.js

项目概述

sse.js 是一个灵活的 Server-Sent Events EventSource 替代方案，专门用于 JavaScript 中消费服务器发送事件流。相比标准的 EventSource，sse.js 提供了更多的控制选项和功能，克服了原生 EventSource 只能支持无负载 GET 请求且无法指定自定义 HTTP 头部的限制。

项目目录结构

sse.js/
├── LICENSE                    # Apache 2.0 许可证文件
├── README.md                  # 项目说明文档
├── bower.json                 # Bower 包管理配置
├── demo.html                  # 使用演示页面
├── lib/                       # 核心库文件目录
│   ├── sse.js                 # 主要实现源码
│   └── sse.test.js           # 测试文件
├── package-lock.json          # npm 依赖锁定文件
├── package.json               # npm 包管理配置
├── tsconfig.json              # TypeScript 配置
└── types/                     # 类型定义目录
    ├── sse.d.ts               # TypeScript 类型定义
    └── sse.d.ts.map           # 类型定义映射文件

快速安装方法

通过 npm 安装

npm install sse.js

通过 CDN 引入

<script type="module">
  import { SSE } from 'https://cdn.jsdelivr.net/npm/sse.js';
</script>

本地文件引入

<script type="module">
  import { SSE } from './lib/sse.js';
</script>

基础使用方法

基本连接示例

import { SSE } from './lib/sse.js';

// 创建 SSE 连接
const source = new SSE('/api/events');

// 监听消息事件
source.addEventListener('message', function (e) {
  // 假设接收 JSON 编码的数据负载：
  const payload = JSON.parse(e.data);
  console.log(payload);
});

延迟启动连接

如果你希望更精确地控制请求触发时机，可以禁用自动启动并在需要时手动调用：

const source = new SSE('/api/events', { start: false });
source.addEventListener('message', (e) => { 
  // 处理消息
});

// 稍后在适当的时候启动流
source.stream();

高级配置选项

自定义请求头

const source = new SSE('/api/events', { 
  headers: { 
    Authorization: 'Bearer your-token',
    'Custom-Header': 'custom-value'
  } 
});

POST 请求支持

通过指定 payload 参数，sse.js 会自动使用 POST 方法：

const source = new SSE('/api/events', {
  headers: { 'Content-Type': 'application/json' },
  payload: JSON.stringify({ filter: 'status=active' })
});

手动覆盖 HTTP 方法

你也可以显式指定 HTTP 方法：

const source = new SSE('/api/events', {
  headers: { 'Content-Type': 'text/plain' },
  payload: 'Hello, world!',
  method: 'GET'
});

自动重连功能

sse.js 支持在连接丢失或遇到错误时自动重新连接：

const source = new SSE('/api/events', {
  autoReconnect: true,        // 启用自动重连
  reconnectDelay: 3000,        // 3 秒后重连
  maxRetries: 5,                // 最多重试 5 次
  useLastEventId: true          // 重连时发送 Last-Event-ID 头部
});

重连状态监控

source.addEventListener('error', (e) => {
  if (source.maxRetries && source.retryCount >= source.maxRetries) {
    console.log('达到最大重试次数，连接永久关闭');
  } else {
    console.log(`连接丢失，将在 ${source.reconnectDelay}ms 后重试');
    console.log(`第 ${source.retryCount + 1} 次尝试${source.maxRetries ? '/' + source.maxRetries : ''}`);
  }
});

Last-Event-ID 支持

Last-Event-ID 头部是 SSE 规范的关键部分，有助于在重新连接时保持消息连续性：

const source = new SSE('/api/events', {
  autoReconnect: true,
  useLastEventId: true,        // 推荐：遵循 SSE 规范
});

事件流顺序

SSE 事件按照以下顺序分发：

事件	描述	触发时机
readystatechange	状态变为 CONNECTING	调用 stream() 方法时
open	连接建立	服务器响应头接收时
readystatechange	状态变为 OPEN	连接建立后
message	数据接收	服务器发送数据时
error	连接错误	连接失败或服务器返回错误时
readystatechange	状态变为 CLOSED	连接关闭时
abort	连接中止	调用 close() 方法时

完整选项参考

选项名称	描述	默认值
headers	包含请求头部的对象	{}
payload	请求负载	""
method	HTTP 方法	自动选择
withCredentials	是否发送 cookie	false
start	是否立即开始流式传输	true
debug	启用调试日志	false
autoReconnect	连接丢失时是否自动尝试重连	false
reconnectDelay	重连前等待时间（毫秒）	3000
maxRetries	最大重连尝试次数	null
useLastEventId	是否在重连时发送 Last-Event-ID 头部以恢复流	true

开发与测试

项目使用 TypeScript 进行开发，并支持 Jest 测试框架：

# 构建项目
npm run build

# 运行测试
npm run test

实际应用场景

sse.js 特别适合以下应用场景：

• 实时通知系统 - 用户消息、状态更新推送
• 数据监控面板 - 实时数据可视化展示
• 股票行情推送 - 金融数据实时更新
• 社交媒体动态 - 新内容实时推送
• 物联网设备监控 - 设备状态实时监控

总结

sse.js 为开发者提供了一个功能丰富且易于使用的 SSE 解决方案，具有以下优势：

• 完全兼容 - 可作为 EventSource 的替代品
• 灵活配置 - 支持自定义头部、负载和方法
• 自动恢复 - 内置连接管理和错误处理机制
• 轻量级 - 不依赖其他库
• 现代支持 - 支持 ES6 模块和现代浏览器特性

通过本指南，你已经掌握了 sse.js 的核心使用方法和最佳实践，可以立即开始在你的项目中集成实时数据推送功能。

【免费下载链接】sse.js A flexible Server-Sent Events EventSource polyfill for Javascript 项目地址: https://gitcode.com/gh_mirrors/ss/sse.js