🚀 從零開始打造一個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/

歡迎關注我的技術分享！