sse.js 使用指南：增强的 Server-Sent Events 解决方案

sse.js 使用指南：增强的 Server-Sent Events 解决方案

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

sse.js 是一个灵活的 JavaScript Server-Sent Events (SSE) EventSource 替代方案，提供了比标准 EventSource 更多的控制和选项。它克服了标准 EventSource 的主要限制，支持自定义请求头和 POST 请求，是构建实时应用的理想选择。

项目简介

sse.js 是一个完全兼容的 EventSource polyfill，可以无缝替换原生 EventSource。如果你需要/想要这样做，只需：

EventSource = SSE;

该库的主要优势包括：

• 支持自定义 HTTP 请求头
• 支持 POST 请求和请求负载
• 完整的 CORS 凭据支持
• 自动重连机制
• 符合 SSE 规范的事件处理

快速开始

安装方式

通过 NPM 安装：

npm install sse.js

基本使用

在模块环境中导入：

import { SSE } from "./sse.js";

在非模块环境中使用：

(async () => {
  const { SSE } = import("./sse.js");
  window.SSE = SSE;
})();

创建 SSE 实例并开始监听事件：

var source = new SSE(url);
source.addEventListener("message", function (e) {
  // 假设我们接收 JSON 编码的数据负载：
  var payload = JSON.parse(e.data);
  console.log(payload);
});

核心功能详解

手动控制连接时机

默认情况下，SSE 会自动执行请求并开始流式传输。如果你希望更精确地控制请求触发时机，可以传递 start: false 选项，稍后调用 stream() 方法：

var source = new SSE(url, {start: false});
source.addEventListener('message', (e) => { ... });
// ... 稍后
source.stream();

自定义请求头

var source = new SSE(url, { headers: { Authorization: "Bearer 0xdeadbeef" } });

POST 请求和 HTTP 方法重写

要发起 HTTP POST 请求，只需在选项中指定 payload：

var source = new SSE(url, {
  headers: { "Content-Type": "text/plain" },
  payload: "Hello, world!",
});

你也可以手动重写用于执行请求的 HTTP 方法，无论是否存在 payload 选项，通过指定 method 选项：

var source = new SSE(url, {
  headers: { "Content-Type": "text/plain" },
  payload: "Hello, world!",
  method: "GET",
});

高级功能

自动重连机制

SSE 支持在连接丢失或遇到错误时自动重连。可以通过选项启用：

var source = new SSE(url, {
  autoReconnect: true, // 启用自动重连
  reconnectDelay: 3000, // 重连前等待 3 秒
  maxRetries: null, // 无限重试（设置数字限制重试次数）
  useLastEventId: true, // 在重连时发送 Last-Event-ID 头（推荐）
});

当启用自动重连时：

• 连接丢失或出现错误时将自动尝试重连
• 每次重连尝试将等待指定的延迟时间（毫秒）
• 如果设置了 maxRetries，重连尝试将在达到该数字后停止
• 如果 useLastEventId 为 true，最后接收的事件 ID 将在 Last-Event-ID 头中发送
• 在 SSE 实例上调用 close() 时，自动重连会自动禁用
• 成功建立连接后，重试计数重置为 0

连接失败后的重连处理

有两种方式处理连接失败后的重连：

1. 自动重连（推荐）

const source = new SSE(url, {
  autoReconnect: true,
  reconnectDelay: 3000,
  maxRetries: 5, // 5 次失败尝试后停止
});

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

2. 手动重连

const source = new SSE(url, { autoReconnect: false });

source.addEventListener("error", (e) => {
  console.log("连接丢失");
  // 等待一段时间然后重连
  setTimeout(() => {
    source.stream();
  }, 3000);
});

// 或者在中止时重连
source.addEventListener("abort", () => {
  source.stream();
});

Last-Event-ID 支持

Last-Event-ID 头是 SSE 规范的关键部分，有助于在重连时维护消息连续性。启用时（默认），SSE 将自动：

1. 跟踪最后接收的事件 ID
2. 在重连尝试时在 Last-Event-ID 头中发送此 ID
3. 允许服务器从中断处恢复事件流

强烈建议保持 useLastEventId 启用，因为它是 SSE 规范的一部分，确保在重连期间不会丢失任何事件。

事件流顺序

SSE 事件按以下顺序分发：

事件	描述	触发时机	事件属性
readystatechange	状态变为 CONNECTING	当调用 stream() 时	readyState: 0
open	连接建立	当服务器响应头被接收时	responseCode, headers
readystatechange	状态变为 OPEN	连接建立后	readyState: 1
message	数据接收	当服务器发送数据时	data, id, lastEventId
error	连接错误	当连接失败或服务器返回错误时	responseCode, data
readystatechange	状态变为 CLOSED	当连接关闭时	readyState: 2
abort	连接中止	当调用 close() 时	无

当启用自动重连时，可能发生以下额外事件：

事件	描述	触发时机	事件属性
readystatechange	状态变为 CONNECTING	当重连开始时	readyState: 0
error	连接错误	当连接失败时	无
readystatechange	状态变为 CLOSED	错误发生后，下一次尝试前	readyState: 2

选项参考

名称	描述
headers	包含要随请求发送的请求头的对象。例如：{'Authorization': 'Bearer 0123456789'}
payload	要随请求发送的请求负载。例如：'{"filter": "temperature > 25"}'
method	使用的 HTTP 方法。如果未指定，有负载时默认为 POST，否则为 GET
withCredentials	是否随请求发送 cookie。默认：false
start	是否立即开始流式传输。默认：true
debug	启用调试日志。默认：false
autoReconnect	连接丢失时是否自动尝试重连。默认：false
reconnectDelay	尝试重连前等待的时间（毫秒）。默认：3000
maxRetries	最大重连尝试次数。设置为 null 表示无限重试。默认：null
useLastEventId	是否在重连时发送 Last-Event-ID 头以恢复流。默认：true

实际应用示例

项目提供了完整的演示页面，展示了 sse.js 的各种功能。演示页面允许用户：

• 输入 SSE 源 URL
• 配置连接设置
• 启用/禁用自动重连
• 设置重连延迟时间
• 限制最大重试次数
• 控制是否使用 Last-Event-ID 头

演示页面实时显示接收到的 SSE 消息，包括连接状态、错误信息和数据内容。

浏览器兼容性

• 现代浏览器：全面支持所有功能
• Internet Explorer 11：需要 custom-event-polyfill 以获得适当的 CustomEvent 支持

sse.js 是一个功能强大且灵活的 SSE 解决方案，为开发者提供了比原生 EventSource 更多的控制能力。无论是构建实时通知系统、数据监控面板还是实时协作应用，sse.js 都能提供稳定可靠的事件流处理能力。

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