CoolQ HTTP API 插件 WebSocket 接口详解

CoolQ HTTP API 插件 WebSocket 接口详解

前言

CoolQ HTTP API 插件作为机器人开发的重要工具，提供了多种通信方式。其中 WebSocket 接口因其全双工通信的特性，在实时性要求高的场景下表现优异。本文将深入解析插件的 WebSocket 接口实现原理和使用方法。

WebSocket 服务端配置

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

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

配置完成后需要重启插件使配置生效。这里的端口可以根据实际需求修改，但要确保不与系统其他服务冲突。

安全认证机制

插件提供了基于 access_token 的安全认证机制，客户端连接时需要提供正确的凭证：

1. 通过 HTTP 头部认证：

Authorization: Token your_access_token_here

2. 通过 URI 参数认证：

/event/?access_token=your_access_token_here

建议在生产环境中务必配置 access_token 以提高安全性。

API 调用接口 (/api/)

请求格式

客户端向 /api/ 接口发送的请求需要遵循特定JSON格式：

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

其中：

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

响应格式

插件返回的响应数据格式如下：

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

响应状态说明：

• status：操作执行状态
• retcode：返回代码（0表示成功）
• data：返回的具体数据

错误代码映射

WebSocket 接口将HTTP状态码转换为retcode：

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

事件推送接口 (/event/)

事件数据格式

通过WebSocket推送的事件数据与HTTP POST上报格式完全一致，包含以下关键字段：

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

与HTTP上报的区别

1. 无签名验证：WebSocket推送不包含类似HTTP的X-Signature头部
2. 无响应处理：客户端无需也不应该对事件推送做出响应
3. 多客户端支持：可同时连接多个客户端接收相同事件

与HTTP上报的共存

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

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

最佳实践建议

1. 连接管理：

   • API接口可保持长连接复用
   • 事件接口建议保持持久连接

2. 错误处理：

   • 实现自动重连机制
   • 监控连接状态

3. 性能优化：

   • 批量处理高频事件
   • 避免在事件处理中进行耗时操作

4. 安全建议：

   • 使用WSS(WebSocket Secure)协议
   • 定期更换access_token
   • 限制可连接IP范围

常见问题解答

Q: WebSocket连接不稳定怎么办？ A: 检查网络状况，实现自动重连机制，考虑使用专业WebSocket客户端库。

Q: 事件处理太慢会丢失消息吗？ A: 不会，但可能导致消息堆积，建议异步处理耗时操作。

Q: 可以同时使用HTTP和WebSocket吗？ A: 可以，两者可以互补使用，根据场景选择合适的方式。

通过本文的详细解析，开发者应该能够全面掌握CoolQ HTTP API插件的WebSocket接口使用方法，在实际项目中灵活运用这种高效的通信方式。