useReactiveSSE

创建响应式 SSE（Server-Sent Events）连接（跨框架实现）

前置依赖

依赖参数

参数名	类型	说明
deps.EventSource	EventSourceConstructor	EventSource 构造函数
deps.setTimeout	typeof setTimeout	定时器函数
deps.clearTimeout	typeof clearTimeout	清除定时器函数
deps.log	Function	可选的日志函数，用于调试

环境要求

• 浏览器环境: 需要支持 EventSource API
• Node.js环境: 需要安装 eventsource 库

npm install eventsource

函数签名

interface UseReactiveSSEDeps {
  EventSource: EventSourceConstructor
  setTimeout: typeof setTimeout
  clearTimeout: typeof clearTimeout
  log?: (...args: any[]) => void
}

interface UseReactiveSSEOptions {
  withCredentials?: boolean
  immediate?: boolean
  reconnect?: SSEReconnectOptions
  onConnected?: (es: EventSource) => void
  onDisconnected?: (es: EventSource, event: any) => void
  onError?: (es: EventSource, event: any) => void
  onMessage?: (es: EventSource, event: any) => void
}

interface SSEReconnectOptions {
  enabled?: boolean
  delay?: number
  maxRetries?: number
  retryDelayMultiplier?: number
}

interface ReactiveSSEState {
  status: SSEStatus
  data: string | null
  lastEventId: string
  error: Error | null
  retryCount: number
  es: EventSource | null
}

interface ReactiveSSEReturn {
  state: ReactiveSSEState
  connect: () => void
  disconnect: () => void
  addEventListener: (type: string, listener: (event: any) => void) => () => void
  subscribe: (listener: () => void) => () => void
  dispose: () => void
}

function useReactiveSSE(
  url: string,
  options?: UseReactiveSSEOptions,
  deps: UseReactiveSSEDeps
): ReactiveSSEReturn

参数

参数名	类型	必填	说明
url	string	是	SSE 服务器地址
options	UseReactiveSSEOptions	否	配置选项
deps	UseReactiveSSEDeps	是	环境依赖

UseReactiveSSEOptions 选项

名称	类型	默认值	说明
withCredentials	boolean	false	是否发送凭证（cookies）
immediate	boolean	true	是否立即连接
reconnect	SSEReconnectOptions	-	重连配置
onConnected	Function	-	连接成功回调
onDisconnected	Function	-	断开连接回调
onError	Function	-	错误回调
onMessage	Function	-	消息回调

SSEReconnectOptions 重连配置

名称	类型	默认值	说明
enabled	boolean	true	是否启用自动重连
delay	number	3000	重连延迟（毫秒）
maxRetries	number	5	最大重连次数，0 表示无限重连
retryDelayMultiplier	number	1.5	重连延迟增长因子

返回值

类型	说明
ReactiveSSEReturn	响应式 SSE 对象

ReactiveSSEReturn 属性和方法

名称	类型	说明
state	ReactiveSSEState	响应式状态对象
connect	() => void	连接 SSE
disconnect	() => void	断开连接
addEventListener	(type, listener) => () => void	添加事件监听器
subscribe	(listener: () => void) => () => void	订阅状态变化
dispose	() => void	销毁实例

ReactiveSSEState 状态对象

名称	类型	说明
status	SSEStatus	连接状态：CONNECTING / CONNECTED / DISCONNECTED / ERROR
data	string | null	最新接收的数据
lastEventId	string	最后一个事件 ID
error	Error | null	错误信息
retryCount	number	当前重连次数
es	EventSource | null	EventSource 实例

工作原理

1. 创建响应式状态对象，包含连接状态、接收数据、事件 ID、错误信息等
2. 根据配置选项创建 EventSource 连接
3. 监听 EventSource 事件（open、message、error）并更新响应式状态
4. 支持自动重连，连接错误时自动尝试重连，重连延迟递增
5. 支持自定义事件监听，可以监听服务器发送的命名事件
6. 提供 connect/disconnect 方法控制连接
7. 通过 subscribe 方法监听状态变化
8. 支持跨框架使用（不依赖 Vue 或其他框架）

SSE vs WebSocket

特性	SSE (useReactiveSSE)	WebSocket (useReactiveWebsocket)
通信方向	单向（服务器→客户端）	双向
协议	HTTP	WebSocket
消息格式	文本（UTF-8）	文本 / 二进制
浏览器重连	自动重连	需要手动实现
事件类型	支持命名事件	统一的 message 事件
复杂度	简单	较复杂
适用场景	实时通知、进度推送	聊天、游戏、实时协作