@giszhc/socket-client：前端web-socket通讯神器，这才是更优解（附在线示例）
Socket Client
一个功能完善、类型安全的 WebSocket 通信客户端库，用于浏览器端 WebSocket 连接。
本库提供了自动重连、心跳机制、namespace 隔离等特性，让 WebSocket 通信更加简单可靠。
✨ 特性
- 🔌开箱即用- 简单的 API，快速集成
- 🔄自动重连- 内置智能重连机制，支持最大重连次数限制
- 💓心跳保活- 自动心跳检测，保持连接活跃
- 🎯Namespace 隔离- 命名空间隔离，避免不同业务消息冲突
- 🛡️类型安全- 完整的 TypeScript 类型支持
- 📦事件订阅- 基于事件类型的订阅机制
- ⚡轻量无依赖- 仅依赖原生 WebSocket API
在线示例
我们提供了一个功能完整的在线演示页面，您可以直接在浏览器中体验所有功能：
🌐 立即体验：点击访问在线演示
安装
pnpminstall@giszhc/socket-client# 或npminstall@giszhc/socket-clientyarnadd@giszhc/socket-client🚀 快速开始
基本使用
import{SocketClient}from'@giszhc/socket-client';constclient=newSocketClient({url:'ws://localhost:8080',// WebSocket 地址namespace:'my-app:chat:v1',// 命名空间（必填）// 可选配置reconnect:true,// 是否自动重连，默认 truemaxReconnectAttempts:5,// 最大重连次数，默认 5reconnectInterval:2000,// 重连间隔（ms），默认 2000heartbeatInterval:10000,// 心跳间隔（ms），默认 10000// 回调函数onConnect:()=>{console.log('✅ 已连接');// 连接成功后发送消息client.sendMessage('JOIN',{roomId:123});},onDisconnect:()=>{console.log('❌ 已断开连接');},onError:(error)=>{console.error('错误:',error);}});// 监听消息client.on('MESSAGE',(data)=>{console.log('收到消息:',data);});// 发送消息client.sendMessage('CHAT',{text:'Hello'});📖 示例
我们提供了完整的示例代码，帮助你快速上手：
在线示例
🌐 立即体验：访问示例页面
运行本地示例
# 1. 安装依赖npminstallws# 2. 启动 WebSocket 服务器nodeexample/server.js# 3. 在浏览器中打开openexample/parent.html详细文档请查看：Example README
📦 消息结构
所有消息会被统一封装为：
{__socket_client__:true,namespace:string,type:string,payload?:any}__socket_client__: 内部标识，用于验证消息来源namespace: 命名空间，用于消息隔离type: 消息类型payload: 消息内容
API
配置项
interfaceSocketClientConfig{/** WebSocket 地址 */url:string;/** 命名空间（必填） */namespace:string;/** 是否自动重连，默认 true */reconnect?:boolean;/** 最大重连次数，默认 5 */maxReconnectAttempts?:number;/** 重连间隔（ms），默认 2000 */reconnectInterval?:number;/** 心跳间隔（ms），默认 10000 */heartbeatInterval?:number;/** 连接成功回调 */onConnect?:()=>void;/** 断开连接回调 */onDisconnect?:()=>void;/** 错误回调 */onError?:(error:Event)=>void;}sendMessage(type, payload)
发送消息到服务器。
client.sendMessage('EVENT_TYPE',{data:'value'});参数：
type: 消息类型（字符串）payload: 消息内容（任意类型）
注意：请在onConnect回调后发送消息，确保连接已建立。
on(type, handler)
监听指定类型的事件。
client.on('MESSAGE',(data,rawEvent)=>{console.log('收到消息:',data);});参数：
type: 事件类型（字符串）handler: 处理函数，接收payload和原始MessageEvent
off(type, handler)
取消监听指定事件。
consthandler=(data)=>{console.log(data);};// 添加监听client.on('MESSAGE',handler);// 移除监听client.off('MESSAGE',handler);isConnected()
检查当前是否已连接。
if(client.isConnected()){console.log('已连接');}else{console.log('未连接');}disconnect()
手动断开连接（禁用自动重连）。
client.disconnect();destroy()
销毁客户端实例，清理所有定时器和监听器。
client.destroy();注意：调用后实例不可再用，需要重新创建。
💡 使用示例
聊天室场景
import{SocketClient}from'@giszhc/socket-client';constchatClient=newSocketClient({url:'ws://localhost:8080/chat',namespace:'chat-room:v1',onConnect:()=>{console.log('加入聊天室');chatClient.sendMessage('JOIN_ROOM',{roomId:'room-123'});}});// 监听新消息chatClient.on('NEW_MESSAGE',(message)=>{console.log(`${message.from}:${message.content}`);});// 发送消息functionsendMessage(content:string){chatClient.sendMessage('SEND_MESSAGE',{content});}// 监听用户加入chatClient.on('USER_JOINED',(user)=>{console.log(`${user.name}加入了房间`);});// 监听用户离开chatClient.on('USER_LEFT',(user)=>{console.log(`${user.name}离开了房间`);});多命名空间隔离
// 聊天服务constchatClient=newSocketClient({url:'ws://localhost:8080',namespace:'app:chat:v1'});// 通知服务constnotifyClient=newSocketClient({url:'ws://localhost:8080',namespace:'app:notification:v1'});// 两个客户端独立工作，互不干扰chatClient.on('MESSAGE',handleChat);notifyClient.on('NOTIFICATION',handleNotify);⚠️ 注意事项
1️⃣ 必须使用 namespace
// ❌ 错误 - 没有隔离namespace:'a'namespace:'b'// ✅ 正确 - 使用分层命名namespace:'my-app:chat:v1'namespace:'my-app:notification:v1'2️⃣ 不要在连接前发送消息
// ❌ 错误constclient=newSocketClient({...});client.sendMessage('INIT');// 可能失败// ✅ 正确constclient=newSocketClient({...onConnect:()=>{client.sendMessage('INIT');}});3️⃣ 及时清理资源
// 组件卸载时useEffect(()=>{constclient=newSocketClient({...});return()=>{client.destroy();// 清理定时器和连接};},[]);4️⃣ 生产环境配置
// ❌ 不建议 - 使用 ws://url:'ws://example.com'// ✅ 推荐 - 使用 wss://url:'wss://your-domain.com/socket'🔧 高级配置
自定义重连策略
constclient=newSocketClient({url:'wss://example.com',namespace:'my-app:v1',// 禁用自动重连reconnect:false});// 手动控制重连client.onDisconnect=()=>{// 自定义重连逻辑setTimeout(()=>{client.connect();},5000);};调整心跳间隔
constclient=newSocketClient({url:'wss://example.com',namespace:'my-app:v1',// 30 秒发送一次心跳heartbeatInterval:30000});🔐 安全建议
- 使用 WSS 协议- 生产环境务必使用加密连接
- 验证 Namespace- 确保命名空间唯一性，避免消息泄露
- Payload 校验- 对接收到的数据进行验证
- 错误处理- 实现完善的错误处理逻辑
❌ 常见问题
Q: onConnect 什么时候触发？
A: 在 WebSocket 连接成功后触发（onopen事件）。
Q: 如何处理重连？
A: 默认启用自动重连，可通过配置调整：
constclient=newSocketClient({reconnect:true,maxReconnectAttempts:5,reconnectInterval:2000});Q: payload 支持什么类型？
A: 支持所有可 JSON 序列化的数据：
- ✅ Object / Array
- ✅ String / Number / Boolean
- ✅ null / undefined
- ❌ Function / DOM 节点
Q: 如何调试？
A: 打开浏览器控制台，库会输出以下日志：
[SocketClient] connected [SocketClient] reconnecting... [SocketClient] not connectedQ: 可以不用这个库吗？
可以，使用原生 WebSocket：
constws=newWebSocket('ws://localhost:8080');ws.onopen=()=>{...};ws.onmessage=(event)=>{...};但你需要自己处理：
- 重连逻辑
- 心跳保活
- 消息管理
- 类型安全
📄 License
MIT
❤️ Made with ❤️ by @giszhc
如果这篇文章对你有帮助，欢迎点赞 👍 收藏 ⭐ 关注 👀
完结，撒花✿✿ヽ(°▽°)ノ✿