TypeScript如何定义WebSocket类型 TS项目WebSocket封装代码【规范】-js教程-PHP中文网

typescript中必须封装websocket而非裸用，因其原生类型缺乏状态管理、自动重连、泛型消息解析等能力；应定义泛型接口websocketmessage明确分离元信息与业务数据，支持按type路由的多类型联合，禁止滥用any或可选字段破坏类型安全。

typescript如何定义websocket类型 ts项目websocket封装代码【规范】

直接结论：TypeScript 中不推荐直接用 WebSocket 原生类型裸写业务逻辑，必须封装 —— 因为原生 WebSocket 缺少连接状态管理、重连控制、消息泛型解析、错误归因等关键能力，裸用必踩断连静默、readyState === 0 时发消息失败、重复绑定事件、心跳失效等坑。

如何正确定义 WebSocket 消息类型（不是 `WebSocket` 类本身）

消息类型定义和 WebSocket 实例类型是两件事。重点在「消息结构」的可推导性，而非套一层 any。

用泛型接口明确区分「消息元信息」和「业务数据」，例如：

interface WebSocketMessage<t unknown> {
  type: string;
  data: T;
  timestamp: number;
}</t>

避免把所有业务消息塞进一个 any 字段；按场景拆分具体类型，如 ChatMessage、NotificationMessage，再通过 type 字段做运行时路由
不要在接口里加可选字段（如 id?: string）来“兼容所有可能”，这会让类型检查形同虚设；宁可定义多个子接口 + 联合类型
服务端返回的字段名若含下划线（如 user_id），TS 接口应保持一致，别强行转驼峰——序列化/反序列化层处理转换，类型层对齐真实 payload

为什么不能直接 new WebSocket(...) 后就往 class 里塞

原生 WebSocket 是无状态裸对象，readyState 变化不可监听，onopen/onmessage 是赋值式覆盖，极易被后续代码无意覆盖。

TypeScript

{"answer":"编写类型安全的 TypeScript，合理运用类型收窄、推断模式与严格模式最佳实践。"}

下载

ws.onmessage = handlerA 之后再写 ws.onmessage = handlerB，handlerA 就永远丢失了
ws.readyState 在连接中可能是 0（CONNECTING），此时调用 ws.send() 直接抛错，但错误不会触发 onerror
没有内置重连逻辑：close 事件触发后，不手动 new WebSocket(...) 就永远断着，且 event.code 和 event.reason 很多时候为空，无法判断是否该重连
心跳必须自己实现：靠 setInterval 发 ping 不够，要配合服务端响应确认，否则单向网络中断时你根本不知道连接已死

封装类必须暴露的最小可控接口

一个可维护的 TS 封装，对外只暴露 4 个核心方法 + 1 个状态字段，其余全部私有。

connect(): void —— 显式触发连接，不自动连接；方便在登录后、权限校验通过后再建链
send<t>(message: WebSocketMessage<t>): boolean</t></t> —— 返回 boolean 表示是否成功入队（非是否送达），失败时应有明确日志（如 “not connected” 或 “buffer full”）
on(event: 'message' | 'open' | 'error' | 'close', callback: Function): void —— 支持多监听器，内部用数组存，避免覆盖
close(isActiveClose?: boolean): void —— 区分主动关闭（不重连）和被动断开（触发重连）
status: WebSocketStatus —— 只读 getter，映射到 ws.readyState，但需加防抖（避免在 CONNECTING 状态快速闪动）

自动重连和心跳的典型陷阱

这两个功能看似简单，实则最容易写出“看起来能跑，线上全崩”的代码。

重连不能无限制：用 reconnectAttempts 计数器 + 指数退避（如第 1 次等 1s，第 2 次等 2s，第 3 次等 4s），避免瞬间打爆服务端 handshake
心跳不能只发不收：只发 ping 不监听 pong 响应，等于没做；正确做法是发 ping 后启动超时定时器，收到 pong 清除定时器，超时则视为连接异常并主动 close()
重连期间禁止重复 connect()：需加 isConnecting: boolean 锁，否则用户快速点击重连按钮会生成多个并发连接
onclose 里不要直接 this.connect()：因为 connect() 会新建 WebSocket 实例，旧实例的事件监听器还挂着，造成内存泄漏