前言

在金融项目中一般需要用到 socket 推送比如行情、订单、K 线等。

痛点一：项目需要同时对接多个不同的 Socket 服务，往往只能创建多个独立的 WebSocket 实例。每个比如实例都要维护心跳，还有重连，再有错误处理，代码重复且难以统一。

痛点二：缺乏统一管理时连接数激增会导致浏览器资源耗尽、网络抖动还有调试困难。老实说，

因为标准的 HTTP/WebSocket 协议是基于特定的 TCP 域名和端口 建立的。无法在同一个原始 WebSocket 管道里直接穿透去连另一个服务。

面对 “多 URL / 多服务” 的需求，常见的调整解法有：

采用网关层聚合—— 最推荐的架构解法

• 做法：在服务端前面挂一层 API 网关 或 BFF 。
• 效果：前端只保持 一个 WebSocket 连接连到网关。发送的消息带上 channel/topic 字段，由网关内部通过高性能 RPC/微服务转发给不同后端。
• 优势：前端极简。仅有一次心跳和重连机制，彻底消灭多连接开销。

金融领域典型场景：同一个 WebSocket 需要兼顾 “无 Symbol 的普通业务` 和 “有 Symbol 的标的业务`”。主要思路是设计一套统一的层级化通信信封与路由映射机制。

统一通信协议

无论业务如何变化。前端与网关之间收发的消息格式都遵循以下规范：

// 前端发给网关的请求结构
interface WSRequest {
action这方面，'SUBSCRIBE' | 'UNSUBSCRIBE' | 'SEND' | 'PING';channel: string;怎么说呢，// 一级通道，例如 'chat'。'order','ticker'
topics?: string，// 二级主题/标的，可选，例如
再看event?不过，，string，// 具体行为/事件名，可选。例如 'send_message'
至于data?，any，// 携带的数据
}
// 网关推给前端的数据包结构
interface WSResponse {
channel: string;// 一级通道
topic?这方面，string，// 二级主题/标的，可选
event?怎么说呢，的观点是，string;// 业务事件名，可选
至于data，T;// 真正业务数据
timestamp: number;// 时间戳
}

实现

心跳保活、指数退避、断线重连、发送队列暂存、连接状态感知等强健机制，并支持网关聚合、多业务场景的公司级 UnifiedWSClient.

// UnifiedWSClient.ts
// ── 状态枚举 ────────────────────────
export enum WSStatus {
CONNECTING = 'CONNECTING'。CONNECTED = 'CONNECTED',DISCONNECTED = 'DISCONNECTED',RECONNECTING = 'RECONNECTING',CLOSED = 'CLOSED',// 主动 close 后不再自动重连
}
// ── 通信信封 ────────────────────────
export interface WSRequest {
说到action，'SUBSCRIBE' | 'UNSUBSCRIBE' | 'SEND' | 'PING';channel: string;topics，: string;event，: string;data，: any;}
export interface WSResponse {
channel: string;topic，怎么说呢，: string;event，: string;data: T，timestamp?: number，}
// ── 配置参数 ────────────────────────
export interface WSClientOptions {
从url来看，string | => string);// 支持函数返回动态 URL
protocols?: string | string;pingInterval?: number，// 心跳间隔 ms，默认15000
pongTimeout?: number，// Pong 超时 ms，默认5000
maxReconnectAttempts?: number，// -1 为无限重连，默认-1
reconnectBaseDelay?: number，// 基础延迟 ms，默认1000
maxReconnectDelay?: number，老实说，// 最大延迟 ms，默认30000
autoConnect?: boolean，// 是否自动 connect，默认 true
}
// ── 回调类型 ────────────────────────
export type MessageCallback = => void;按理说，export type EventListener = => void;按理说，// ── UnifiedWSClient 主体 ────────────────────────
export class UnifiedWSClient {
private urlGetter: => string;private protocols?说起来，: string | string;// 合并后的完整配置项
private options: Required;不过，// 主要属性
private ws: WebSocket | null = null;private status: WSStatus = WSStatus.DISCONNECTED;// 定时器集合
private pingTimer: any = null;private pongTimer: any = null;说起来，private reconnectTimer:any = null;// 重连控制
private reconnectAttempts = 0;private isExplicitlyClosed = false;// 未就绪时缓存待发送消息
private messageQueue:Array=;// EventEmitter：内部状态变化通知
private eventListeners= new Map>
// 路由分发：routeKey → Set
private subscribers= new Map>
constructor {
this.urlGetter = typeof options.url === 'function'?options.url : => options.url;this.protocols = options.protocols;this.options = {
pingInterval : options.pingInterval?，老实说，15000。pongTimeout : options.pongTimeout?，怎么说呢，5000。maxReconnectAttempts : options.maxReconnectAttempts?，-1,reconnectBaseDelay : options.reconnectBaseDelay?，1000,maxReconnectDelay : options.maxReconnectDelay?，30000,autoConnect : options.autoConnect?，true,};if this.connect;}
/* ==================== 主要连接控制 ==================== */
public connect {
if ) return;this.isExplicitlyClosed = false;const initStatus = this.reconnectAttempts> 0?WSStatus.RECONNECTING : WSStatus.CONNECTING;this.setStatus;try {
const url = this.urlGetter;this.ws = new WebSocket;this.initEvents;} catch {
this.emit;this.handleReconnect;}
}
public isNormal: boolean { return this.status===WSStatus.CONNECTED && this.ws?.readyState===WebSocket.OPEN;}
public getStatus: WSStatus { return this.status;}
public close{
this.isExplicitlyClosed=true;this.clearAllTimers;this.messageQueue=;if{ this.ws.close;this.ws=null;}
this.setStatus;}
public on{
if) this.eventListeners.set);this.eventListeners.get!.add，}
public off{ this.eventListeners.get?.delete，}
/* ==================== 高层业务 API ==================== */
/**
* subscription API
* - 无 topic 场景：ws.subscribe
* - 单 topic 场景：ws.subscribe
* - 多 topic 场景：ws.subscribe
*/
public subscribe:=>void{
const topicList= topics?
，topics:) :;按理说，if{
const isFirst=this.addSubscription;if this.sendGatewayAction;}else{
const newTopics:string=;topicList.forEach(topic=>{
const routeKey=`${channel}:${topic}`;const isFirst=this.addSubscription;按理说，if newTopics.push;})，if this.sendGatewayAction;话说回来，}
return=>this.unsubscribe;怎么说呢，}
public unsubscribe{
const topicList= topics?，topics:) :;if{
const hasRemaining=this.removeSubscription;老实说，if this.sendGatewayAction;}else{
const toUnsub:string=;topicList.forEach(topic=>{
const routeKey=`${channel}:${topic}`;const hasRemaining=this.removeSubscription;if toUnsub.push;})，if this.sendGatewayAction;}
}
/**
* 发业务消息；说起来，若未就绪会自动加入发送队列
*/
public send{
const payload:WSRequest={action:'SEND'。channel,event,data,topics:};this.sendRaw);说起来，}
/* ==================== 底层事件绑定 ==================== */
private initEvents{
if return;/* ---- open ---- */
this.ws.onopen==>{
\t\t\tthis.reconnectAttempts=0;\t\t\tthis.setStatus;\t\t\tthis.startHeartbeat;\t\t\tthis.flushMessageQueue;\t\t\tthis.resubscribeAll;\t\t\tthis.emit;}，
 /* ---- message ---- */
this.ws.onmessage==>{
/* 收到任意数据即复位心跳计时 */
this.resetHeartbeatTimeout;try{
const msg:WSResponse=JSON.parse;/* 心跳 Pong 忽略 */
if return;const routeKey=msg.topic?`${msg.channel}:${msg.topic}` : msg.channel;const cbs=this.subscribers.get;if{
cbs.forEach);}
}catch{
console.error;}
}，/* ---- error ---- */
this.ws.onerror==>{this.emit;}，/* ---- close ---- */
this.ws.onclose==>{
this.clearAllTimers;this.ws=null;this.emit，if{
// 非主动关闭走自动重连流程
this.setStatus;this.handleReconnect;}
}，}
/* ==================== 心跳保活 ==================== */
private startHeartbeat{
this.stopHeartbeat;// 防止重复启动
this.pingTimer=setInterval=>{
if){
// 发 Ping 包给网关程序层面进行心跳检测
const pingPayload={action:'PING'。channel:'system',event:'ping'};this.sendRaw);// 设置 Pong 超时阈值；超时则强制关闭触发重连逻辑
if clearTimeout;按理说，\tthis.pongTimer=setTimeout=>{
console.warn;\tthis.ws，.close;// 将触发 onclose → handleReconnect
},this.options.pongTimeout);}
},\tthis.options.pingInterval);}
private resetHeartbeatTimeout{
if{clearTimeout;按理说，\t{this.connect;},delay)，}
/* ------------------- 重连成功后恢复全部订阅 ------------------- */
private resubscribeAll{
const channelTopicMap=new Map;\t{
\tconst =routeKey.split;\tif) channelTopicMap.set;\tif channelTopicMap.get!.push，});channelTopicMap.forEach=>{
\tconst payloadTopics=topics.length?不过，topics : undefined;\t$this.sendGatewayAction;})，}
/* ==================== 基础设施 & 辅助方法 ==================== */
/** 添加订阅；返回是否为首个订阅者，用于决定是否向网关发送 SUBSCRIBE 指令 */
private addSubscription:boolean{
let set=this.subscribers.get;if{set=new Set;\t


}

/** 将缓存队列中的消息逐条发送直至队列为空或
掉线 */
private flushMessageQueue{
while){
const msg=this.messageQueue.shift;if .ws，.send;// 类型断言安全，因为仅缓存字符串或二进制块。}
}

/* 状态变更并广播 statusChange */
private setStatus:void{
if{
const prev=this.status;.status=next;.emit，}
}
/* 清理所有计时器 /
private clearAllTimers{
.stopHeartbeat;if{clearTimeout;.reconnectTimer=null;}
}
/* 简单 EventEmitter 实现 */
private emit{
.eventListeners.get?.forEach，}catch{console.error;} })，}
}


Demo

import { UnifiedWSClient,WSStatus } from './UnifiedWSClient';


// ---------- 初始化全局唯一实例 ----------
export const wsClient = new UnifiedWSClient({
url : => wss://gateway.example.com/ws?token=${localStorage.getItem},pingInterval : 10000,// 每10秒一次心跳
pongTimeout :3000。maxReconnectAttempts:-1,// 无限重连，可自行调小防止死循环

});

// ---------- 全局网络状态感知 ----------
wsClient.on=>{
if{
console.log;}else if{
console.warn;怎么说呢，}else{
console.error;}
}，

// ---------- 示例组件 A：聊天 ----------
const unsubChat = wsClient.subscribe=>|{
console.log;})，怎么说呢，wsClient.send;

// ---------- 示例组件 B：行情看板 ----------
const unsubTicker = wsClient.subscribe(
'ticker',=>{ console.log;},)，

// 动态追加 SOL 行情订阅
const unsubSol= wsClient.subscribe(
'ticker',=>{ console.log;},'SOL-USDT'
);

// ---------- 页面销毁 / Component Unmount ----------
unsubChat;// 自动引用计数降至0后 SDK 会向网关发送 UNSUBSCRIBE
unsubTicker;unsubSol，unsubKline;

// ---------- 使用者登出或应用退出 ----------
wsClient.close;// 主动关闭，不再自动重连




# 主要收益：


仅一条物理链接 ⇒ 大幅降低浏览器资源使用情况与网络抖动风险。

统一 Envelope 协议 + 路由分发，让业务代码不再关注底层细节。

指数退避 + 心跳保活 + 消息队列缓存，实现“断线即恢复”。

* 可根据实际需求进一步
：鉴权刷新、压缩传输、加密签名等。


* 若你的项目仍在使用多个散落的 WebSocket 实例，请考虑迁移到上述 UnifiedWSClient + 网关聚合 立即解决多连接带来的性能瓶颈和运维痛点！