🚀 从零开始打造一个WebSocket客户端库：websocket-fruge365

📖 前言

在现代Web开发中，实时通信已经成为不可或缺的功能。无论是聊天应用、实时数据监控，还是在线协作工具，WebSocket都扮演着重要角色。然而，原生的WebSocket API使用起来相对复杂，缺乏自动重连、错误处理等实用功能。

今天，我将分享如何从零开始打造一个功能完善的WebSocket客户端库 —— websocket-fruge365。

🎯 项目目标

在开始编码之前，我们先明确这个库要解决的问题：

• ✅ 简化API：提供更简洁易用的接口
• ✅ 自动重连：网络断开时自动尝试重连
• ✅ 错误处理：完善的错误处理机制
• ✅ TypeScript支持：提供完整的类型定义
• ✅ 跨平台：同时支持浏览器和Node.js环境

🛠️ 技术选型

• 语言：JavaScript (ES6+)
• 模块系统：ES Modules
• 类型定义：TypeScript Declaration Files
• 包管理：npm
• Node.js支持：ws库

🏗️ 核心架构设计

1. 状态管理

let socket = null;
let handleMessage = null;
let handleErr = null;
let reconnectAttempts = 0;
let maxReconnectAttempts = 5;
let reconnectInterval = 3000;
let isManualClose = false;
let originalUrl = '';
let originalToken = null;

2. 核心连接函数

function initSocket(url, token = null) {
  if (typeof WebSocket === "undefined") {
    console.error("初始化失败, 不支持使用WebSocket");
    return false;
  }
  
  const protocols = token ? [token] : undefined;
  
  try {
    socket = new WebSocket(url, protocols);
  } catch (error) {
    console.error('WebSocket连接创建失败:', error);
    return false;
  }

  // 绑定事件处理器
  socket.onopen = socketOnOpen;
  socket.onmessage = socketOnMessage;
  socket.onerror = socketOnError;
  socket.onclose = socketOnClose;
  
  return true;
}

3. 自动重连机制

socket.onclose = (e) => {
  console.log('连接关闭', e.code, e.reason);
  if (!isManualClose && reconnectAttempts < maxReconnectAttempts) {
    setTimeout(() => {
      reconnectAttempts++;
      console.log(`尝试重连 (${reconnectAttempts}/${maxReconnectAttempts})`);
      initSocket(originalUrl, originalToken);
    }, reconnectInterval);
  }
};

🔧 关键功能实现

1. 连接管理

export function connectSocket(url, options = {}) {
  if (!url) {
    console.error('WebSocket URL不能为空');
    return false;
  }
  
  const {
    token = null,
    onMessage = null,
    onError = null,
    maxReconnectAttempts: maxAttempts = 5,
    reconnectInterval: interval = 3000
  } = options;
  
  // 设置全局配置
  maxReconnectAttempts = maxAttempts;
  reconnectInterval = interval;
  
  if (onMessage) handleMessage = onMessage;
  if (onError) handleErr = onError;

  // 保存原始参数用于重连
  originalUrl = url;
  originalToken = token;
  
  return initSocket(url, token);
}

2. 消息发送

export function sendMessage(data) {
  if (!socket) {
    console.error('WebSocket未初始化');
    return false;
  }
  
  if (socket.readyState === WebSocket.OPEN) {
    try {
      const message = typeof data === 'string' ? data : JSON.stringify(data);
      socket.send(message);
      return true;
    } catch (error) {
      console.error('发送消息失败:', error);
      return false;
    }
  } else {
    console.warn('WebSocket连接未就绪, 当前状态:', socket.readyState);
    return false;
  }
}

3. 状态检查

export function getSocketState() {
  if (!socket) return 'CLOSED';
  
  switch (socket.readyState) {
    case WebSocket.CONNECTING: return 'CONNECTING';
    case WebSocket.OPEN: return 'OPEN';
    case WebSocket.CLOSING: return 'CLOSING';
    case WebSocket.CLOSED: return 'CLOSED';
    default: return 'UNKNOWN';
  }
}

export function isConnected() {
  return socket && socket.readyState === WebSocket.OPEN;
}

📝 TypeScript类型定义

为了提供更好的开发体验，我们添加了完整的TypeScript类型定义：

export interface WebSocketOptions {
  /** 可选的token参数 */
  token?: string;
  /** 获取websocket传过来的数据后的处理函数 */
  onMessage?: (event: MessageEvent) => void;
  /** websocket连接出错后的处理函数 */
  onError?: (error: Event) => void;
  /** 最大重连次数，默认5次 */
  maxReconnectAttempts?: number;
  /** 重连间隔，默认3000ms */
  reconnectInterval?: number;
}

export type SocketState = 'CONNECTING' | 'OPEN' | 'CLOSING' | 'CLOSED' | 'UNKNOWN';

🎨 使用示例

基本用法

import { connectSocket, sendMessage, closeSocket } from 'websocket-fruge365';

// 连接WebSocket
connectSocket('ws://localhost:8080', {
  onMessage: (event) => {
    console.log('收到消息:', event.data);
  },
  onError: (error) => {
    console.error('连接错误:', error);
  }
});

// 发送消息
sendMessage({ type: 'hello', message: 'Hello WebSocket!' });

// 关闭连接
closeSocket();

Vue3中使用

<script setup>
import { connectSocket, sendMessage, closeSocket } from 'websocket-fruge365';
import { onMounted, onUnmounted } from 'vue';

const initWebSocket = () => {
  connectSocket('ws://localhost:8080', {
    onMessage: (event) => {
      console.log('收到消息:', event.data);
    },
    onError: (error) => {
      console.error('连接错误:', error);
    }
  });
  
  // 等待连接建立后发送消息
  setTimeout(() => {
    sendMessage({ type: 'hello', message: 'Hello from Vue3!' });
  }, 1000);
}

onMounted(() => {
  initWebSocket();
});

onUnmounted(() => {
  closeSocket();
});
</script>

聊天应用示例

import { connectSocket, sendMessage, isConnected } from 'websocket-fruge365';

class ChatClient {
  constructor(url, userId) {
    this.userId = userId;
    this.connect(url);
  }

  connect(url) {
    connectSocket(`${url}?userId=${this.userId}`, {
      onMessage: this.handleMessage.bind(this),
      onError: this.handleError.bind(this),
      maxReconnectAttempts: 5,
      reconnectInterval: 3000
    });
  }

  handleMessage(event) {
    const message = JSON.parse(event.data);
    console.log(`${message.user}: ${message.text}`);
  }

  sendChatMessage(text) {
    if (isConnected()) {
      sendMessage({
        type: 'chat',
        user: this.userId,
        text: text,
        timestamp: Date.now()
      });
    }
  }
}

📦 发布到npm

1. 准备package.json

{
  "name": "websocket-fruge365",
  "version": "1.0.5",
  "description": "一个简单易用的WebSocket客户端库，支持自动重连、错误处理和消息管理",
  "main": "index.js",
  "module": "index.js",
  "type": "module",
  "files": [
    "index.js",
    "socket.js",
    "README.md",
    "types.d.ts"
  ],
  "keywords": [
    "websocket",
    "socket",
    "realtime",
    "client",
    "reconnect",
    "javascript",
    "browser",
    "nodejs"
  ],
  "author": "fruge365",
  "license": "MIT"
}

2. 发布流程

# 登录npm
npm login

# 发布包
npm publish

🚀 项目亮点

1. 简洁的API设计

• 只需要一个函数调用即可建立连接
• 参数通过options对象传递，清晰明了
• 提供了常用的工具函数

2. 健壮的错误处理

• 连接失败时的自动重连
• 详细的错误日志输出
• 优雅的降级处理

3. 完善的开发体验

• 完整的TypeScript类型定义
• 详细的文档和示例
• 支持多种使用场景

4. 跨平台兼容

• 浏览器环境原生支持
• Node.js环境通过ws库支持
• 统一的API接口

🔍 遇到的挑战与解决方案

1. 重连时参数丢失问题

问题：初始连接失败后，重连时token等参数会丢失。

解决方案：在连接时保存原始参数，重连时使用保存的参数。

// 保存原始参数用于重连
originalUrl = url;
originalToken = token;

2. Node.js环境兼容性

问题：Node.js环境没有原生WebSocket支持。

解决方案：使用ws库，并在文档中说明使用方法。

// Node.js环境
global.WebSocket = require('ws');
import { connectSocket } from 'websocket-fruge365';

3. API设计的简化

问题：最初的API设计过于复杂，有params参数等冗余设计。

解决方案：简化API，移除不必要的参数，让用户直接在URL中包含查询参数。

📈 性能优化

1. 内存管理：及时清理事件监听器和定时器
2. 错误边界：添加try-catch保护关键代码
3. 状态检查：发送消息前检查连接状态
4. 参数验证：对输入参数进行有效性检查

🔮 未来规划

• 添加心跳检测机制
• 支持消息队列和批量发送
• 添加连接池管理
• 提供更多的配置选项
• 添加单元测试覆盖

📚 总结

通过这个项目，我学到了：

1. API设计的重要性：简洁易用的API是库成功的关键
2. 错误处理的必要性：完善的错误处理能大大提升用户体验
3. 文档的价值：好的文档能让用户快速上手
4. 类型定义的作用：TypeScript支持能提升开发效率
5. 测试的重要性：充分的测试能保证代码质量

🔗 相关链接

• GitHub仓库：https://github.com/fruge365/WebSocket
• npm包：https://www.npmjs.com/package/websocket-fruge365
• 作者博客：https://fruge365.blog.csdn.net/

🎉 结语

开发一个npm包是一个很好的学习过程，不仅能加深对技术的理解，还能为开源社区做出贡献。希望这个WebSocket客户端库能帮助到更多的开发者，也欢迎大家提出建议和贡献代码！

如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！

---

关于作者

我是fruge365，一名热爱技术的前端开发者。专注于Web开发、JavaScript、Vue.js等技术领域。

• GitHub: https://github.com/fruge365
• CSDN博客: https://fruge365.blog.csdn.net/

欢迎关注我的技术分享！