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 polyfill。它提供了比标准EventSource更多的控制选项和功能，让开发者能够发送带有自定义头部和载荷的请求，支持多种HTTP方法，是现代实时应用开发的理想选择。

项目核心优势

相比原生EventSource，sse.js在以下几个方面展现出显著优势：

高度可定制化请求 - 支持自定义请求头和多种HTTP方法，满足复杂业务场景需求。原生EventSource仅支持无载荷的GET请求，且无法指定额外的自定义HTTP请求头。

智能连接管理 - 内置完善的自动重连机制和连接状态监控，确保数据流稳定传输。支持配置重连延迟时间和最大重试次数。

开发者友好设计 - 提供调试模式和详细的事件监听，内置Last-Event-ID支持，遵循SSE规范确保消息连续性。

快速上手指南

环境要求与安装

sse.js兼容现代浏览器环境，安装过程极其简单：

npm install sse.js

基础配置与初始化

通过几行代码即可创建功能完整的SSE客户端：

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

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

模块导入方式

从模块上下文导入：

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

从非模块上下文导入：

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

高级功能配置

自定义请求头配置

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方法：

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

自动重连功能

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

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

连接状态管理

如果需要更精确地控制连接时机，可以传递start: false选项，稍后调用stream()方法：

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

事件处理机制

事件流顺序

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()时	无

响应头与状态码

SSE端点的响应头和服务器返回的状态码在流开始时触发的open事件中暴露：

var source = new SSE(url);
source.addEventListener("open", function (e) {
  console.log(
    "Got a " + e.responseCode + " response with headers: " + e.headers
  );
});
source.stream();

完整选项参考

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

开发与构建

构建项目

使用以下命令构建项目：

npm run build

运行测试

npm test

sse.js作为完全兼容的EventSource polyfill，如果你需要/想要，可以这样做：

EventSource = SSE;

这个包旨在提供一个可用的EventSource替代品，使所有这些成为可能。无论你是前端新手还是资深开发者，sse.js都能为你提供稳定可靠的服务器推送解决方案。

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