SocketServer

SocketServer 对象表示一个已经建立的 WebSocket 连接。通过它，你可以和客户端进行消息交互，包括接收消息、发送数据，以及监听连接的关闭与错误事件。

下面是SocketServer对象的所有方法：

名称	类型	参数	返回值	说明
`on`	方法	`eventName:string,callback(msg, messageType)`	`void`	监听客户端发来的消息
`send`	方法	`message:string \| byte[]`	`void`	向客户端发送一条消息（支持字符串或二进制）
`close`	方法		`void`	主动关闭当前连接

on

wsCtx对象可以通过on方法来监听事件，支持3种事件：message,error,close。

事件监听方法

on("message", callback(msg, messageType)) 监听客户端发来的消息。
- msg：消息内容（文本或二进制数据）
- messageType：消息类型（"text" | "binary"）
on("error", callback(err)) 监听连接发生错误时的回调。
- err：错误对象或错误信息
on("close", callback()) 监听客户端主动断开连接或服务端关闭连接时的回调。

示例

server.ws("/socket", (wsServer, ctx) => {
    // 监听消息
    wsServer.on("message", (msg, messageType) => {
        console.log("消息内容:", msg);
    });

    // 监听错误
    wsServer.on("error", (err) => {
        console.error("WebSocket 错误:", err);
        wsServer.close();
    });

    // 监听关闭
    wsServer.on("close", () => {
        console.log("客户端断开:", ctx.remoteAddr);
    });
});

send

消息发送方法

send(data) 向客户端发送一条消息（支持字符串或二进制）。

示例

server.ws("/socket", (wsServer, ctx) => {
    //给客户端发送消息
    wsServer.on("message", (msg, messageType) => {
        wsServer.send("接收到来自客户端消息：" + msg);
    });
});

close

关闭连接方法

close() 主动关闭当前连接。

示例

server.ws("/socket", (wsServer, ctx) => {
    // 监听错误
    wsServer.on("error", (err) => {
        console.error("WebSocket 错误:", err);
        wsServer.close();
    });
});

生命周期说明

一个 SocketServer（即单个客户端连接）的生命周期通常分为以下几个阶段：

连接建立
- 当客户端成功发起 WebSocket 握手后，服务端会触发 server.ws(url, callback) 的回调。
- 在回调中，你可以获取当前连接的 SocketServer 对象（wsServer）和上下文对象（SocketCtx）。
```
server.ws("/socket", (wsServer, ctx) => {
    console.log("新连接来自:", ctx.remoteAddr);
});
```
消息收发
- 连接建立后，客户端和服务端可以进行双向通信。
- 服务端通过 wsServer.on("message") 监听消息，通过 wsServer.send() 发送消息。
```
wsServer.on("message", (msg, type) => {
    console.log("收到消息:", msg);
    wsServer.send("响应: " + msg);
});
```
错误处理
- 如果连接过程中发生异常，wsServer.on("error") 会被触发。
- 常见情况：消息格式不正确、网络中断、非法操作等。
- 建议在出错时调用 wsServer.close() 主动关闭连接，避免资源泄漏。
```
wsServer.on("error", (err) => {
    console.error("连接出错:", err);
    wsServer.close();
});
```
连接关闭
- 当客户端主动断开，或者服务端调用 wsServer.close() 时，wsServer.on("close") 会被触发。
- 你可以在这里清理资源、移除用户会话等。
```
wsServer.on("close", () => {
    console.log("客户端断开:", ctx.remoteAddr);
});
```

📌 总结：

建立阶段：握手完成，进入回调。
通信阶段：on("message") 与 send() 实现全双工通信。
异常阶段：通过 on("error") 捕获错误并关闭连接。
关闭阶段：on("close") 清理资源，结束生命周期。

完整代码示例

import {HttpServer} from "http";

let server = new HttpServer({addr: ":9999"});

server.ws("/socket", (wsServer, ctx) => {
    console.log("客户端连接建立:", ctx.remoteAddr);

    // 监听消息
    wsServer.on("message", (msg, messageType) => {
        console.log("消息类型:", messageType);
        console.log("消息内容:", msg);

        if (messageType === "text") {
            if (msg === "ping") {
                wsServer.send("pong");
            } else if (msg === "test") {
                wsServer.send("测试成功响应");
            } else {
                try {
                    const data = JSON.parse(msg);
                    if (data.event === "login") {
                        console.log("用户登录:", data.data);
                        wsServer.send(JSON.stringify({
                            event: "login_response",
                            data: {success: true}
                        }));
                    }
                } catch (e) {
                    console.error("无效的 JSON:", msg);
                }
            }
        }
    });

    // 监听错误
    wsServer.on("error", (err) => {
        console.error("WebSocket 错误:", err);
        wsServer.close();
    });

    // 监听关闭
    wsServer.on("close", () => {
        console.log("客户端断开:", ctx.remoteAddr);
    });
});

server.start();

SocketServer

ON THIS PAGE