CoolQ HTTP API 插件通信方式详解

贺晔音

于 2025-06-27 09:13:08 发布

阅读量232

点赞数 5

CC 4.0 BY-SA版权

本文链接：https://blog.csdn.net/gitblog_00340/article/details/148944447

CoolQ HTTP API 插件通信方式详解

前言

CoolQ HTTP API 插件为开发者提供了多种与酷Q交互的通信方式，本文将全面解析这些通信方式的工作原理、适用场景及具体实现方法，帮助开发者根据实际需求选择最合适的通信方案。

通信方式概览

CoolQ HTTP API 插件主要支持三种核心通信方式：

HTTP 服务端模式：插件作为HTTP服务器提供API服务
WebSocket 服务端模式：插件作为WebSocket服务器提供服务
反向WebSocket模式：插件作为WebSocket客户端主动连接外部服务

这三种方式分别通过配置项use_http、use_ws和use_ws_reverse进行控制。此外，插件还支持通过HTTP上报事件，这一功能独立于上述三种通信方式。

HTTP 服务端模式详解

核心特点

HTTP服务端模式是插件最基础也是最易用的通信方式，具有以下特点：

采用标准的HTTP协议
请求-响应模型简单直观
支持直接通过URL调用API
提供数据文件访问功能

适用场景

本地开发与快速测试
单机部署环境
需要直接访问数据文件的场景
对实时性要求不高的应用

配置与使用

在配置文件中设置：

use_http = yes
host = 0.0.0.0  # 监听所有网络接口
port = 5700     # 默认端口

API调用示例：

http://localhost:5700/send_private_msg?user_id=123456&message=你好

数据文件访问：

http://localhost:5700/get_image?file=xxxxxx

注意事项

确保防火墙开放了对应端口
生产环境建议配置access_token增强安全性
长时间运行的业务应考虑连接池管理

WebSocket 服务端模式详解

核心特点

WebSocket服务端模式提供了持久化的双向通信通道：

低延迟的双向通信
事件驱动架构
支持长连接
分离的API和事件通道

适用场景

需要实时通信的应用
浏览器端集成
高频率交互场景
无法使用HTTP上报的环境

配置与使用

配置文件设置：

use_ws = yes
ws_host = 0.0.0.0
ws_port = 6700

连接端点：
- API调用：ws://localhost:6700/api/
- 事件接收：ws://localhost:6700/event/

典型工作流程：

// 连接API端点
const apiWs = new WebSocket('ws://localhost:6700/api/');

apiWs.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('API响应:', response);
};

// 发送API请求
apiWs.send(JSON.stringify({
  action: 'send_private_msg',
  params: { user_id: 123456, message: '你好' }
}));

高级特性

echo机制：解决响应顺序问题，可在请求中添加唯一标识
心跳检测：建议客户端实现心跳保持连接
多客户端支持：允许多个客户端同时连接

反向WebSocket模式详解

核心特点

反向WebSocket模式是插件作为客户端主动连接外部服务器的模式：

插件主动发起连接
穿透性好，适合无公网IP场景
支持API和事件分离
自动重连机制

适用场景

酷Q运行在内网的场景
业务服务有公网IP的情况
需要集中管理的多机器人架构
需要更高安全控制的场景

配置与使用

基础配置：

use_ws_reverse = yes
ws_reverse_api_url = ws://your-server.com/api/
ws_reverse_event_url = ws://your-server.com/event/

服务端识别信息：
- X-Self-ID：机器人QQ号
- X-Client-Role：客户端类型(API/Event)
- Authorization：认证令牌(如配置)

断线重连配置：

ws_reverse_reconnect_interval = 3000  # 重试间隔(毫秒)
ws_reverse_reconnect_on_code_1000 = yes  # 是否在正常关闭时重连

实现建议

服务端设计：
- 实现路由分发，根据X-Client-Role处理不同业务
- 维护连接状态，处理异常断开
- 实现心跳机制检测连接健康度
性能优化：
- 使用连接池管理多个机器人连接
- 考虑消息队列处理高并发事件
- 实现请求限流保护

通信方式对比与选型

| 特性 | HTTP服务端 | WebSocket服务端 | 反向WebSocket | |---------------------|------------|-----------------|---------------| | 网络要求 | 需公网IP | 需公网IP | 业务端需公网IP| | 实时性 | 低 | 高 | 高 | | 连接方向 | 插件被动 | 插件被动 | 插件主动 | | 穿透性 | 差 | 差 | 优 | | 开发复杂度 | 简单 | 中等 | 中等 | | 适合场景 | 简单应用 | 实时应用 | 内网部署 |