WebSocket API 文档

WebSocket API 为 EasyBot 插件提供了完整的 WebSocket 客户端和服务端功能，支持实时双向通信。

WebSocket 客户端

CreateClient()

功能: 创建 WebSocket 客户端

语法: CreateClient(url: string, id?: string): string

参数:

url (string): WebSocket 服务器地址
id (string, 可选): 客户端ID，为空则自动生成

返回值: string - 客户端ID

示例:

const clientId = ws.CreateClient("ws://localhost:8080", "my-client");
logger.info("客户端ID:", clientId);

ConnectAsync()

功能: 连接 WebSocket 服务器

语法: ConnectAsync(id: string): Promise<boolean>

参数:

id (string): 客户端ID

返回值: Promise<boolean> - 是否连接成功

示例:

const connected = await ws.ConnectAsync("my-client");
if (connected) {
    logger.info("连接成功");
}

DisconnectAsync()

功能: 断开 WebSocket 连接

语法: DisconnectAsync(id: string): Promise<boolean>

参数:

id (string): 客户端ID

返回值: Promise<boolean> - 是否断开成功

示例:

const disconnected = await ws.DisconnectAsync("my-client");

SendTextAsync()

功能: 发送文本消息

语法: SendTextAsync(id: string, message: string): Promise<boolean>

参数:

id (string): 客户端ID
message (string): 消息内容

返回值: Promise<boolean> - 是否发送成功

示例:

const sent = await ws.SendTextAsync("my-client", "Hello Server!");

SendBinaryAsync()

功能: 发送二进制消息

语法: SendBinaryAsync(id: string, data: Uint8Array): Promise<boolean>

参数:

id (string): 客户端ID
data (Uint8Array): 二进制数据

返回值: Promise<boolean> - 是否发送成功

示例:

const binaryData = new Uint8Array([1, 2, 3, 4]);
const sent = await ws.SendBinaryAsync("my-client", binaryData);

SetMessageCallback()

功能: 设置消息接收回调

语法: SetMessageCallback(id: string, callback: (message: string, data: Uint8Array | null) => void): boolean

参数:

id (string): 客户端ID
callback (function): 回调函数

返回值: boolean - 是否设置成功

示例:

ws.SetMessageCallback("my-client", (message, data) => {
    if (message) {
        logger.info("收到文本消息:", message);
    }
    if (data) {
        logger.info("收到二进制数据:", data);
    }
});

SetStateCallback()

功能: 设置连接状态变化回调

语法: SetStateCallback(id: string, callback: (state: number) => void): boolean

参数:

id (string): 客户端ID
callback (function): 回调函数

返回值: boolean - 是否设置成功

示例:

ws.SetStateCallback("my-client", (state) => {
    logger.info("连接状态变化:", state);
});

GetClientState()

功能: 获取客户端状态

语法: GetClientState(id: string): number

参数:

id (string): 客户端ID

返回值: number - 客户端状态

示例:

const state = ws.GetClientState("my-client");
logger.info("当前状态:", state);

DestroyClientAsync()

功能: 销毁客户端

语法: DestroyClientAsync(id: string): Promise<boolean>

参数:

id (string): 客户端ID

返回值: Promise<boolean> - 是否销毁成功

示例:

const destroyed = await ws.DestroyClientAsync("my-client");

GetClientIds()

功能: 获取所有客户端ID

语法: GetClientIds(): string[]

返回值: string[] - 客户端ID列表

示例:

const clientIds = ws.GetClientIds();
logger.info("所有客户端:", clientIds);

WebSocket 服务端

CreateServer()

功能: 创建 WebSocket 服务器

语法: CreateServer(port: number, id?: string, host?: string, path?: string): string

参数:

port (number): 监听端口
id (string, 可选): 服务器ID，为空则自动生成
host (string, 可选): 监听地址，默认为 localhost
path (string, 可选): 监听路径，默认为 "/"

返回值: string - 服务器ID

示例:

const serverId = ws.CreateServer(8080, "my-server", "localhost", "/ws");

StartServerAsync()

功能: 启动 WebSocket 服务器

语法: StartServerAsync(id: string): Promise<boolean>

参数:

id (string): 服务器ID

返回值: Promise<boolean> - 是否启动成功

示例:

const started = await ws.StartServerAsync("my-server");

StopServerAsync()

功能: 停止 WebSocket 服务器

语法: StopServerAsync(id: string): Promise<boolean>

参数:

id (string): 服务器ID

返回值: Promise<boolean> - 是否停止成功

示例:

const stopped = await ws.StopServerAsync("my-server");

SendToClientAsync()

功能: 向指定客户端发送文本消息

语法: SendToClientAsync(serverId: string, clientId: string, message: string): Promise<boolean>

参数:

serverId (string): 服务器ID
clientId (string): 客户端ID
message (string): 消息内容

返回值: Promise<boolean> - 是否发送成功

示例:

const sent = await ws.SendToClientAsync("my-server", "client-123", "Hello Client!");

SendBinaryToClientAsync()

功能: 向指定客户端发送二进制消息

语法: SendBinaryToClientAsync(serverId: string, clientId: string, data: Uint8Array): Promise<boolean>

参数:

serverId (string): 服务器ID
clientId (string): 客户端ID
data (Uint8Array): 二进制数据

返回值: Promise<boolean> - 是否发送成功

示例:

const data = new Uint8Array([5, 6, 7, 8]);
const sent = await ws.SendBinaryToClientAsync("my-server", "client-123", data);

BroadcastAsync()

功能: 广播文本消息给所有客户端

语法: BroadcastAsync(serverId: string, message: string): Promise<boolean>

参数:

serverId (string): 服务器ID
message (string): 消息内容

返回值: Promise<boolean> - 是否发送成功

示例:

const sent = await ws.BroadcastAsync("my-server", "广播消息给所有客户端");

BroadcastBinaryAsync()

功能: 广播二进制消息给所有客户端

语法: BroadcastBinaryAsync(serverId: string, data: Uint8Array): Promise<boolean>

参数:

serverId (string): 服务器ID
data (Uint8Array): 二进制数据

返回值: Promise<boolean> - 是否发送成功

示例:

const data = new Uint8Array([9, 10, 11, 12]);
const sent = await ws.BroadcastBinaryAsync("my-server", data);

SetConnectionCallback()

功能: 设置客户端连接回调

语法: SetConnectionCallback(serverId: string, callback: (clientId: string) => void): boolean

参数:

serverId (string): 服务器ID
callback (function): 回调函数

返回值: boolean - 是否设置成功

示例:

ws.SetConnectionCallback("my-server", (clientId) => {
    logger.info("客户端连接:", clientId);
});

SetDisconnectionCallback()

功能: 设置客户端断开连接回调

语法: SetDisconnectionCallback(serverId: string, callback: (clientId: string, status: number | null, description: string | null) => void): boolean

参数:

serverId (string): 服务器ID
callback (function): 回调函数

返回值: boolean - 是否设置成功

示例:

ws.SetDisconnectionCallback("my-server", (clientId, status, description) => {
    logger.info("客户端断开:", clientId, status, description);
});

SetServerMessageCallback()

功能: 设置消息接收回调

语法: SetServerMessageCallback(serverId: string, callback: (clientId: string, message: string, data: Uint8Array | null) => void): boolean

参数:

serverId (string): 服务器ID
callback (function): 回调函数

返回值: boolean - 是否设置成功

示例:

ws.SetServerMessageCallback("my-server", (clientId, message, data) => {
    logger.info("收到消息来自:", clientId);
    if (message) logger.info("文本:", message);
    if (data) logger.info("二进制数据长度:", data.length);
});

IsServerRunning()

功能: 获取服务器状态

语法: IsServerRunning(serverId: string): boolean

参数:

serverId (string): 服务器ID

返回值: boolean - 服务器是否运行中

示例:

if (ws.IsServerRunning("my-server")) {
    logger.info("服务器正在运行");
}

GetServerClients()

功能: 获取服务器的客户端列表

语法: GetServerClients(serverId: string): string[]

参数:

serverId (string): 服务器ID

返回值: string[] - 客户端ID列表

示例:

const clients = ws.GetServerClients("my-server");
logger.info("连接的客户端:", clients);

DestroyServerAsync()

功能: 销毁服务器

语法: DestroyServerAsync(serverId: string): Promise<boolean>

参数:

serverId (string): 服务器ID

返回值: Promise<boolean> - 是否销毁成功

示例:

const destroyed = await ws.DestroyServerAsync("my-server");

GetServerIds()

功能: 获取所有服务器ID

语法: GetServerIds(): string[]

返回值: string[] - 服务器ID列表

示例:

const serverIds = ws.GetServerIds();
logger.info("所有服务器:", serverIds);

使用示例

WebSocket 客户端示例

// 创建并连接客户端
const clientId = ws.CreateClient("ws://localhost:8080");

// 设置回调
ws.SetMessageCallback(clientId, (message, data) => {
    logger.info("收到消息:", message);
});

ws.SetStateCallback(clientId, (state) => {
    logger.info("连接状态:", state);
});

// 连接服务器
const connected = await ws.ConnectAsync(clientId);
if (connected) {
    // 发送消息
    await ws.SendTextAsync(clientId, "Hello Server!");
}

WebSocket 服务端示例

// 创建并启动服务器
const serverId = ws.CreateServer(8080, "chat-server");

// 设置回调
ws.SetConnectionCallback(serverId, (clientId) => {
    logger.info("新客户端连接:", clientId);
    ws.SendToClientAsync(serverId, clientId, "欢迎连接!");
});

ws.SetServerMessageCallback(serverId, (clientId, message, data) => {
    logger.info(`客户端 ${clientId} 发送:`, message);
    // 广播给所有客户端
    ws.BroadcastAsync(serverId, `${clientId}: ${message}`);
});

ws.SetDisconnectionCallback(serverId, (clientId) => {
    logger.info("客户端断开:", clientId);
});

// 启动服务器
await ws.StartServerAsync(serverId);

聊天室示例

// 创建聊天服务器
const chatServer = ws.CreateServer(9000, "chat-room");

// 存储客户端信息
const clients = new Map<string, { name: string }>();

ws.SetConnectionCallback(chatServer, (clientId) => {
    clients.set(clientId, { name: `用户${clientId.slice(-4)}` });
    
    // 通知其他用户有新用户加入
    const joinMessage = `${clients.get(clientId)?.name} 加入了聊天室`;
    ws.BroadcastAsync(chatServer, joinMessage);
});

ws.SetServerMessageCallback(chatServer, (clientId, message) => {
    const client = clients.get(clientId);
    if (client && message) {
        // 广播聊天消息
        const chatMessage = `${client.name}: ${message}`;
        ws.BroadcastAsync(chatServer, chatMessage);
    }
});

ws.SetDisconnectionCallback(chatServer, (clientId) => {
    const client = clients.get(clientId);
    if (client) {
        const leaveMessage = `${client.name} 离开了聊天室`;
        ws.BroadcastAsync(chatServer, leaveMessage);
        clients.delete(clientId);
    }
});

await ws.StartServerAsync(chatServer);
logger.info("聊天室服务器已启动在端口 9000");

注意事项

异步操作: 连接、发送、断开等操作都是异步的
状态管理: 注意检查连接状态再进行操作
资源清理: 使用完毕后记得销毁客户端和服务器
错误处理: 对异步操作进行适当的错误处理
端口冲突: 确保服务器端口未被占用
权限要求: 监听所有网络接口可能需要管理员权限

最佳实践

使用有意义的ID便于管理
设置适当的回调函数处理各种事件
在插件卸载时清理所有WebSocket资源
对消息进行适当的验证和处理
考虑连接重试机制提高稳定性

WebSocket 客户端​

CreateClient()​

ConnectAsync()​

DisconnectAsync()​

SendTextAsync()​

SendBinaryAsync()​

SetMessageCallback()​

SetStateCallback()​

GetClientState()​

DestroyClientAsync()​

GetClientIds()​

WebSocket 服务端​

CreateServer()​

StartServerAsync()​

StopServerAsync()​

SendToClientAsync()​

SendBinaryToClientAsync()​

BroadcastAsync()​

BroadcastBinaryAsync()​

SetConnectionCallback()​

SetDisconnectionCallback()​

SetServerMessageCallback()​

IsServerRunning()​

GetServerClients()​

DestroyServerAsync()​

GetServerIds()​

使用示例​

WebSocket 客户端示例​

WebSocket 服务端示例​

聊天室示例​

注意事项​

最佳实践​

WebSocket 客户端

CreateClient()

ConnectAsync()

DisconnectAsync()

SendTextAsync()

SendBinaryAsync()

SetMessageCallback()

SetStateCallback()

GetClientState()

DestroyClientAsync()

GetClientIds()

WebSocket 服务端

CreateServer()

StartServerAsync()

StopServerAsync()

SendToClientAsync()

SendBinaryToClientAsync()

BroadcastAsync()

BroadcastBinaryAsync()

SetConnectionCallback()

SetDisconnectionCallback()

SetServerMessageCallback()

IsServerRunning()

GetServerClients()

DestroyServerAsync()

GetServerIds()

使用示例

WebSocket 客户端示例

WebSocket 服务端示例

聊天室示例

注意事项

最佳实践