nodejs-websocket API完全参考：开发者必备手册

nodejs-websocket API完全参考：开发者必备手册

【免费下载链接】nodejs-websocketA node.js module for websocket server and client项目地址: https://gitcode.com/gh_mirrors/no/nodejs-websocket

nodejs-websocket是一个专为Node.js设计的WebSocket服务器和客户端模块，提供了简单易用的API来实现实时双向通信。这个轻量级库让开发者能够快速构建WebSocket应用，支持文本和二进制数据传输，是构建实时聊天应用、游戏服务器和实时数据推送系统的理想选择。

📦 快速安装与配置

要开始使用nodejs-websocket，首先需要通过npm安装：

npm install nodejs-websocket

安装完成后，在您的项目中引入模块：

var ws = require("nodejs-websocket");

🚀 核心API详解

服务器端API

ws.createServer([options], [callback])

创建WebSocket服务器的主要方法。这个方法返回一个Server对象，用于监听客户端连接。

参数说明：

• options(可选)：传递给net.createServer()的对象。如果包含secure: true属性，则使用tls.createServer()
• callback(可选)：连接建立时的回调函数，自动添加为'connection'事件监听器

支持协议的选项：

• validProtocols：服务器接受的协议名称数组
• selectProtocol：协议协商回调函数，接收连接对象和客户端协议列表

示例代码：

// 创建简单服务器 var server = ws.createServer(function(conn) { console.log("新连接建立"); // 处理连接事件 }).listen(8001); // 创建安全服务器 var secureServer = ws.createServer({ secure: true }, function(conn) { console.log("安全连接建立"); }).listen(8443);

server.listen(port, [host], [callback])

启动服务器监听指定端口。

参数说明：

• port：监听的端口号
• host(可选)：主机地址，默认为任何IPv4地址
• callback(可选)：服务器开始监听时的回调函数

server.close([callback])

停止服务器接受新连接，但保持现有连接。

客户端API

ws.connect(URL, [options], [callback])

创建WebSocket客户端连接，返回Connection对象。

参数说明：

• URL：WebSocket服务器地址，格式为"ws://localhost:8000/chat"或"wss://"（安全连接）
• options(可选)：传递给net.connect()或tls.connect()的对象
• callback(可选)：连接成功时的回调函数

选项属性：

• extraHeaders：添加额外的HTTP握手请求头
• protocols：协议协商数组

示例代码：

// 创建客户端连接 var conn = ws.connect("ws://localhost:8000/chat", function() { console.log("连接到服务器"); }); // 带额外选项的连接 var connWithOptions = ws.connect("ws://localhost:8000/chat", { extraHeaders: { 'X-My-Header': 'value' }, protocols: ['chat', 'game'] });

🔌 Connection对象API详解

Connection对象代表一个WebSocket连接，可以是服务器端接受的连接，也可以是客户端创建的连接。

数据发送方法

connection.sendText(str, [callback])

发送文本数据到另一端。不能在二进制传输过程中发送文本数据。

参数说明：

• str：要发送的字符串
• callback(可选)：数据最终写出时执行的回调函数

connection.beginBinary()

请求一个OutStream对象来发送二进制数据。返回一个可写流，用于分块发送二进制数据。

connection.sendBinary(data, [callback])

一次性发送单个二进制数据块（相当于调用connection.beginBinary().end(data)）。

参数说明：

• data：Buffer类型的二进制数据
• callback(可选)：数据最终写出时执行的回调函数

connection.send(data, [callback])

发送字符串或Buffer到另一端。这是sendText()和sendBinary()的便捷别名。

connection.sendPing([data=''])

发送ping到远程端，用于心跳检测。当收到pong回复时会触发'pong'事件。

connection.close([code, [reason]])

关闭连接，发送关闭帧并等待响应。如果连接不是OPEN状态，则不发送关闭帧直接关闭。

连接属性

事件监听

Connection对象继承自EventEmitter，支持以下事件：

'close(code, reason)'

连接关闭时触发，传递关闭代码和原因。

'error(err)'

发生错误时触发，传递错误对象。

'text(str)'

收到文本数据时触发，传递接收到的字符串。

'binary(inStream)'

收到二进制数据时触发，传递可读流对象。

'pong(data)'

收到pong回复时触发，传递ping数据。

'connect'

客户端连接成功建立时触发。

📊 全局配置方法

ws.setBinaryFragmentation(bytes)

设置二进制数据在单个帧中发送的最小包大小。

ws.setMaxBufferLength(bytes)

设置内部Buffer的最大增长大小，防止内存攻击。

🏗️ 实际应用示例

简单回声服务器

var ws = require("nodejs-websocket"); // 创建服务器 var server = ws.createServer(function(conn) { console.log("新连接建立"); // 监听文本消息 conn.on("text", function(str) { console.log("收到消息: " + str); // 回声响应 conn.sendText("服务器收到: " + str); }); // 监听连接关闭 conn.on("close", function(code, reason) { console.log("连接关闭，代码: " + code + "，原因: " + reason); }); // 监听错误 conn.on("error", function(err) { console.error("连接错误: ", err); }); }).listen(8001); console.log("WebSocket服务器运行在端口 8001");

实时聊天服务器

var ws = require("nodejs-websocket"); var connections = []; var server = ws.createServer(function(conn) { connections.push(conn); console.log("新用户加入，当前在线: " + connections.length); // 广播消息给所有客户端 function broadcast(message) { connections.forEach(function(client) { if (client.readyState === 1) { // OPEN状态 client.sendText(message); } }); } conn.on("text", function(message) { console.log("收到消息: " + message); broadcast("用户: " + message); }); conn.on("close", function() { var index = connections.indexOf(conn); if (index > -1) { connections.splice(index, 1); } console.log("用户离开，剩余在线: " + connections.length); }); }).listen(8080);

二进制文件传输

var ws = require("nodejs-websocket"); var fs = require("fs"); var server = ws.createServer(function(conn) { conn.on("binary", function(inStream) { // 创建文件写入流 var fileStream = fs.createWriteStream("received_file.bin"); // 管道传输二进制数据 inStream.pipe(fileStream); inStream.on("end", function() { conn.sendText("文件接收完成"); }); }); // 发送二进制文件 conn.on("text", function(filename) { fs.readFile(filename, function(err, data) { if (err) { conn.sendText("读取文件错误: " + err.message); } else { conn.sendBinary(data, function() { conn.sendText("文件发送完成"); }); } }); }); }).listen(3000);

🔧 高级配置与最佳实践

安全连接配置

var ws = require("nodejs-websocket"); var fs = require("fs"); // 读取SSL证书 var options = { secure: true, key: fs.readFileSync('server-key.pem'), cert: fs.readFileSync('server-cert.pem') }; var secureServer = ws.createServer(options, function(conn) { console.log("安全连接建立"); // 处理连接 }).listen(8443);

协议协商

var server = ws.createServer({ validProtocols: ['chat-v1', 'chat-v2'], selectProtocol: function(conn, protocols) { // 选择客户端支持的最新版本 if (protocols.indexOf('chat-v2') !== -1) { return 'chat-v2'; } else if (protocols.indexOf('chat-v1') !== -1) { return 'chat-v1'; } return ''; // 没有匹配的协议 } }, function(conn) { console.log("协商的协议: " + conn.protocol); });

🚨 错误处理与调试

连接状态管理

var conn = ws.connect("ws://localhost:8000"); // 检查连接状态 console.log("连接状态: " + conn.readyState); // 状态常量 console.log("CONNECTING: " + conn.CONNECTING); // 0 console.log("OPEN: " + conn.OPEN); // 1 console.log("CLOSING: " + conn.CLOSING); // 2 console.log("CLOSED: " + conn.CLOSED); // 3 // 监听所有可能的事件 conn.on("connect", function() { console.log("连接成功建立"); }); conn.on("close", function(code, reason) { console.log("连接关闭，代码: " + code + "，原因: " + reason); }); conn.on("error", function(err) { console.error("连接错误: ", err); });

性能优化配置

// 设置二进制分片大小（字节） ws.setBinaryFragmentation(8192); // 8KB // 设置最大缓冲区长度 ws.setMaxBufferLength(1048576); // 1MB

📈 常见用例场景

1. 实时数据推送

使用nodejs-websocket可以轻松实现股票行情、体育比分、新闻推送等实时数据更新功能。

2. 多人协作应用

构建实时协作编辑器、白板应用或多人在线游戏，利用WebSocket的双向通信能力。

3. 即时通讯系统

实现聊天应用、客服系统或团队协作工具，支持文本和文件传输。

4. IoT设备通信

连接物联网设备，实现设备状态监控和远程控制。

🎯 总结与建议

nodejs-websocket作为一个轻量级的WebSocket实现，提供了简洁而强大的API接口。对于需要实时双向通信的Node.js应用来说，它是一个优秀的选择。通过本文的完整API参考，您应该能够：

1. 快速上手：理解基本概念和安装配置
2. 掌握核心API：熟练使用服务器和客户端方法
3. 处理不同类型数据：文本和二进制数据传输
4. 构建健壮应用：错误处理和性能优化
5. 实现实际场景：聊天、文件传输、实时推送等

记住，WebSocket连接是持久化的，适合需要频繁数据交换的场景。对于简单的请求-响应模式，传统的HTTP可能更合适。

开始您的实时应用开发之旅吧！🚀

【免费下载链接】nodejs-websocketA node.js module for websocket server and client项目地址: https://gitcode.com/gh_mirrors/no/nodejs-websocket