CoolQ HTTP API 消息格式深度解析

CoolQ HTTP API 消息格式深度解析

前言

在机器人开发领域，消息处理是核心功能之一。本文将深入探讨 CoolQ HTTP API 中的消息格式体系，帮助开发者更好地理解和运用这一功能强大的机器人框架。

消息格式概述

CoolQ HTTP API 提供了两种消息格式支持：

1. 字符串格式：传统的单一字符串表示方式
2. 数组格式：结构化的消息段数组表示方式

这两种格式在以下场景中均可使用：

• 发送消息（API调用）
• 上报消息（事件通知）
• 回复消息（快速响应）

字符串格式详解

字符串格式是酷Q原生支持的消息格式，其特点是将所有内容（包括文本和多媒体）编码在一个字符串中。

核心特点

1. 统一编码：文本和多媒体内容混合编码
2. CQ码机制：使用特殊语法表示多媒体内容
3. 转义需求：需要对特殊字符进行转义处理

CQ码结构示例

[CQ:image,file=example.jpg]

其中：

• image 表示功能类型
• file=example.jpg 是参数键值对

转义规则

字符串格式中需要转义的特殊字符包括：

• [ → [
• ] → ]
• & → &
• 其他XML/HTML特殊字符

消息段（广义CQ码）概念

为了支持更结构化的消息处理，CoolQ HTTP API 引入了"消息段"概念，这是对传统CQ码的扩展和规范化。

消息段结构

{
    "type": "消息类型",
    "data": {
        "参数1": "值1",
        "参数2": "值2"
    }
}

特殊消息段 - 文本

纯文本使用特殊的text类型表示：

{
    "type": "text",
    "data": {
        "text": "纯文本内容"
    }
}

数组格式详解

数组格式由多个消息段组成，提供了更清晰、更易处理的消息表示方式。

优势分析

1. 结构化：明确区分文本和多媒体内容
2. 无需转义：各字段值均为真实值
3. 易扩展：方便添加新的消息类型
4. 易处理：程序解析更简单

转换示例

传统字符串格式：

[标题][CQ:image,file=1.jpg]内容[CQ:face,id=123]

对应的数组格式：

[
    {"type":"text","data":{"text":"[标题]"}},
    {"type":"image","data":{"file":"1.jpg"}},
    {"type":"text","data":{"text":"内容"}},
    {"type":"face","data":{"id":"123"}}
]

格式选择建议

使用字符串格式的场景

1. 需要与旧系统兼容
2. 处理简单文本消息
3. 人工阅读和调试时

使用数组格式的场景

1. 需要精确控制消息结构
2. 处理复杂多媒体消息
3. 程序化生成消息内容
4. 需要更好的可维护性

最佳实践

1. 新项目推荐：优先使用数组格式
2. 格式转换：框架提供自动转换能力
3. 混合处理：可根据场景灵活选择
4. 性能考量：简单消息用字符串，复杂消息用数组

总结

CoolQ HTTP API 的双格式消息系统为开发者提供了灵活的选择空间。理解这两种格式的特点和适用场景，能够帮助开发者构建更健壮、更易维护的机器人应用。数组格式代表了更现代的解决方案，特别适合复杂的消息处理场景，而字符串格式则保持了良好的兼容性。