SSE

规划 API： 本页说明 SSE 的最终用户用法。commflow@0.0.2 尚未导出 SSE runtime；不要将本页 import 当作当前生产导入。当前可运行导出见当前版本快速开始。

适用场景

SSE 适合服务端向客户端持续推送事件：

场景	是否适合
通知、状态更新、任务进度	适合
服务端单向事件流	适合
浏览器或网关更容易接受 HTTP 流	适合
客户端也需要持续发送消息	使用 Socket
一次性请求/响应	使用 Request

创建 SSE client

import { createCommflowSseClient } from 'commflow';

const sse = createCommflowSseClient({
  baseURL: 'https://events.example.com',
  reconnect: {
    attempts: 5,
    delay: 1000
  }
});

配置	用户含义
`baseURL`	事件服务地址。
`reconnect.attempts`	断线后最多重连次数。
`reconnect.delay`	重连基础延迟。

订阅事件

const stream = sse.subscribe('/notifications', {
  onMessage(event) {
    console.log(event.type, event.data);
  },
  onError(error) {
    console.error('sse failed', error);
  }
});

订阅返回的 stream 必须提供关闭能力，用户可以在页面卸载、服务关闭或业务完成时释放连接。

处理事件类型

const stream = sse.subscribe('/jobs/42/events', {
  onMessage(event) {
    if (event.type === 'job.progress') {
      updateProgress(event.data.percent);
    }

    if (event.type === 'job.done') {
      markDone(event.data.result);
    }
  }
});

推荐按事件类型分支处理，不要把所有消息都塞进一个无结构字符串。

鉴权与 Last-Event-ID

const stream = sse.subscribe('/jobs/42/events', {
  headers: {
    authorization: `Bearer ${token}`
  },
  lastEventId: resumeFromLastSeenId(),
  onMessage(event) {
    rememberLastSeenId(event.id);
  }
});

字段	目标行为
`headers`	建连时发送鉴权、tenant 或 trace headers。
`lastEventId`	断线恢复时从最后消费的事件继续。
`event.id`	用户应在业务侧持久化或至少保存在当前会话中。
`onMessage`	消息处理失败不应悄悄吞掉，应进入可观测错误路径。

重连策略

SSE 断线不一定是业务失败，可能只是网络抖动。建议：

场景	建议
短暂网络断开	自动重连。
鉴权过期	暴露给业务，刷新 token 后重新订阅。
服务端返回不可恢复错误	停止重连并提示用户。
页面或任务结束	主动关闭，不再重连。

状态模型：

状态	含义
`connecting`	正在建立 HTTP 事件流。
`open`	已连接并可接收事件。
`reconnecting`	非主动关闭后等待下一次连接。
`closed`	用户主动关闭或任务结束。
`failed`	重连耗尽或遇到不可恢复错误。

关闭与资源释放

await stream.close();

必须释放的场景：

前端组件卸载。
服务端 request lifecycle 结束。
用户切换 tenant、project 或 topic。
任务已完成，不再需要进度事件。

错误处理

SSE 错误需要区分：

错误	处理
网络中断	按 retry 策略重连。
服务端拒绝	暴露给业务处理。
消息解析失败	记录原始消息和 topic，避免吞掉诊断信息。
重连耗尽	进入最终失败状态。

更多错误模型见错误与重试。

不适合 SSE 的场景

如果需要客户端持续发送消息、房间广播、二进制数据或强交互实时通道，应使用 Socket，不要用 SSE 模拟双向协议。

#SSE

#适用场景

#创建 SSE client

#订阅事件

#处理事件类型

#鉴权与 Last-Event-ID

#重连策略

#关闭与资源释放

#错误处理

#不适合 SSE 的场景

SSE