CoolQ HTTP API 插件 WebSocket 接口详解

CoolQ HTTP API 插件 WebSocket 接口详解

前言

CoolQ HTTP API 插件作为连接 CoolQ 机器人与开发者程序的重要桥梁，提供了多种通信方式。其中 WebSocket 协议因其全双工通信特性，在实时性要求较高的场景下表现优异。本文将深入解析该插件的 WebSocket 接口实现细节，帮助开发者更好地构建机器人应用。

WebSocket 服务端配置

要启用 WebSocket 服务端功能，需要在插件配置文件中进行以下设置：

ws_host=0.0.0.0  # 监听所有网络接口
ws_port=6700     # 服务端口号
use_ws=yes       # 启用WebSocket服务

配置完成后需要重启插件使配置生效。这里的端口号可以根据实际需求修改，但要注意避免与其他服务端口冲突。

安全认证机制

插件提供了基于 Token 的认证机制，确保连接的安全性。开发者可以通过两种方式传递 access_token：

1. HTTP 头方式：

Authorization: Token your_access_token_here

2. URL 参数方式：

/api/?access_token=your_access_token_here

建议在生产环境中始终启用 access_token 验证，避免未授权访问。

API 调用接口 (/api/)

请求格式

通过 WebSocket 调用 API 时，需要发送如下结构的 JSON 数据：

{
    "action": "api_name",
    "params": {
        "param1": "value1",
        "param2": "value2"
    }
}

其中：

• action：指定要调用的 API 名称
• params：API 所需的参数对象（可选）

响应格式

插件会返回标准的响应结构：

{
    "status": "ok|failed",
    "retcode": 0,
    "data": {...}
}

错误代码映射

WebSocket 接口使用特定的 retcode 来映射 HTTP 状态码：

| retcode | HTTP 状态码 | 说明 | |---------|------------|------| | 1400 | 400 | 请求错误 | | 1401 | 401 | 未授权 | | 1403 | 403 | 禁止访问 | | 1404 | 404 | API 不存在 |

连接管理建议

开发者可以采用两种连接策略：

1. 长连接：保持单个连接重复使用
2. 短连接：每次调用 API 时新建连接

对于高频调用的场景，推荐使用长连接以减少连接建立的开销。

事件推送接口 (/event/)

事件数据格式

事件推送的数据格式与 HTTP POST 上报完全一致，包含以下核心字段：

{
    "post_type": "message|notice|request|...",
    "time": 1630000000,
    "self_id": 123456,
    // 其他事件特定字段
}

与 HTTP 上报的区别

1. 无签名验证：WebSocket 推送不包含类似 HTTP 上报的 X-Signature 签名头
2. 无响应处理：客户端无需也不应该对事件推送做出响应
3. 实时性更高：相比 HTTP 请求，WebSocket 能更快地传递事件

多推送渠道共存

当同时配置了 WebSocket 和 HTTP 上报时：

1. 插件会先通过 HTTP 向 post_url 上报
2. 等待 HTTP 响应处理完成后
3. 向所有已连接的 WebSocket 客户端推送事件

这种设计确保了不同上报方式间的数据一致性。

最佳实践建议

1. 错误处理：始终检查返回的 status 和 retcode 字段
2. 心跳机制：建议实现 WebSocket 心跳以保持连接活跃
3. 重连逻辑：网络异常时应有自动重连机制
4. 流量控制：避免短时间内发送大量 API 请求
5. 日志记录：记录重要的事件和 API 调用情况

结语

CoolQ HTTP API 插件的 WebSocket 接口为开发者提供了高效、实时的机器人交互方式。通过合理利用 /api/ 和 /event/ 两个接口，开发者可以构建出响应迅速、功能丰富的机器人应用。在实际开发中，建议根据具体场景选择合适的通信方式，并注意处理好各种边界情况和异常状态。