Socket

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

适用场景

socket 适合长连接双向实时通信：

场景	是否适合
聊天、协作、房间消息	适合
实时状态同步	适合
客户端和服务端都要主动发消息	适合
服务端单向事件流	可使用 SSE
一次性请求/响应	使用 Request

创建 socket client

import { createCommflowSocketClient } from 'commflow';

const socket = createCommflowSocketClient({
  url: 'wss://socket.example.com',
  heartbeatInterval: 30000,
  reconnect: {
    attempts: 5,
    delay: 1000
  }
});

配置	用户含义
`url`	WebSocket 服务地址。
`heartbeatInterval`	心跳间隔。
`reconnect`	断线重连策略。

连接与关闭

await socket.connect();

// ...使用连接

await socket.close();

连接生命周期必须显式。用户应该知道什么时候连接、什么时候关闭，以及关闭后是否还会重连。

发送消息

await socket.send({
  type: 'chat.message',
  payload: {
    roomId: 'room-a',
    text: 'hello'
  }
});

推荐消息结构：

字段	含义
`type`	消息类型。
`payload`	业务数据。
`requestId`	可选，用于关联响应或诊断。

发送顺序与背压：

场景	目标行为
连接未打开时发送	默认进入待发送队列，或按用户配置立即失败。
重连期间发送	保留顺序，重连成功后按入队顺序发送。
服务端或浏览器缓冲区过高	暴露 `drain` 或 backpressure 状态，避免无限堆内存。
用户主动关闭	清空队列，不再自动重发。

监听事件

const unsubscribe = socket.on('message', (message) => {
  console.log(message.type, message.payload);
});

unsubscribe();

监听必须可释放，避免页面切换、服务关闭或重复订阅后产生资源泄漏。

心跳与重连

场景	建议
心跳超时	视为连接不可用，触发重连或失败。
网络短断	按 reconnect 策略重连。
服务端主动关闭	根据 close reason 判断是否重连。
用户主动关闭	不应自动重连。

重新订阅：

const socket = createCommflowSocketClient({
  url: 'wss://socket.example.com',
  reconnect: { attempts: 5, delay: 1000 },
  resubscribeOnReconnect: true
});

await socket.subscribe('room-a');

重连后是否自动重新订阅必须由配置控制。默认不应重复发送会产生副作用的业务消息；只恢复订阅、presence 或只读状态同步这类可安全重放的动作。

鉴权与会话

socket 连接常需要 token 或 session：

const socket = createCommflowSocketClient({
  url: 'wss://socket.example.com',
  auth() {
    return {
      token: getAccessToken()
    };
  }
});

鉴权过期时，应让用户能刷新 token 后重连，而不是无限重连失败。

资源释放

必须释放的资源：

message listener。
reconnect timer。
heartbeat timer。
pending request/response correlation。
socket connection。

错误处理

错误	处理
网络断开	可重连。
鉴权失败	刷新 token 或提示重新登录。
协议错误	记录消息和 close reason。
主动关闭	不重连。

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

#Socket

#适用场景

#创建 socket client

#连接与关闭

#发送消息

#监听事件

#心跳与重连

#鉴权与会话

#资源释放

#错误处理