深入理解CoolQ HTTP API插件的WebSocket通信机制

深入理解CoolQ HTTP API插件的WebSocket通信机制

概述

CoolQ HTTP API插件通过WebSocket协议为开发者提供了另一种与机器人交互的方式。相比于传统的HTTP接口，WebSocket具有全双工通信、低延迟等优势，特别适合需要实时交互的场景。本文将详细介绍如何配置和使用CoolQ HTTP API插件的WebSocket功能。

WebSocket基础配置

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

ws_host=0.0.0.0  # 监听所有网络接口
ws_port=6700     # 设置监听端口
use_ws=yes       # 启用WebSocket功能

配置完成后需要重启插件使配置生效。如果只需要WebSocket功能，可以同时禁用HTTP接口：

use_http=no      # 禁用HTTP接口

安全认证机制

为了保障通信安全，插件提供了基于access_token的认证机制。建立WebSocket连接时，需要在请求头中加入认证信息：

Authorization: Token your_access_token_here

或者直接在连接URI中指定：

/ws/api/?access_token=your_access_token_here

API调用接口(/api/)

通过连接/api/接口，开发者可以调用各种机器人API。调用方式为发送特定格式的JSON请求：

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

请求参数说明

• action: 指定要调用的API名称
• params: API所需的参数对象(可选)

响应格式

插件会返回JSON格式的响应，结构如下：

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

错误代码对照表

WebSocket接口使用特定的retcode来表示错误，与HTTP状态码对应关系如下：

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

事件推送接口(/event/)

通过连接/event/接口，开发者可以实时接收各种事件通知。事件数据格式与HTTP POST上报完全一致，但有以下区别：

1. 不包含签名信息(X-Signature)
2. 不处理客户端响应
3. 可以与HTTP上报同时使用

事件处理建议

当需要根据事件调用API时，建议：

1. 使用单独的HTTP接口
2. 或建立另一个WebSocket连接到/api/接口

实践建议

1. 连接管理：对于/api/接口，可以根据需要选择保持长连接或按需建立短连接
2. 错误处理：合理处理retcode，特别是1404表示请求的API不存在
3. 性能优化：高频API调用建议使用WebSocket长连接，减少连接建立开销
4. 安全建议：务必设置复杂的access_token并妥善保管

总结

CoolQ HTTP API插件的WebSocket功能为开发者提供了更加灵活和高效的机器人交互方式。通过合理配置和使用，可以构建响应更快速、体验更流畅的机器人应用。无论是API调用还是事件接收，WebSocket都是传统HTTP接口的有力补充。