深入解析CoolQ HTTP API中的消息格式

深入解析CoolQ HTTP API中的消息格式

前言

在机器人开发中，消息处理是核心功能之一。CoolQ HTTP API提供了灵活的消息格式支持，开发者可以根据需求选择不同的格式来处理消息。本文将全面解析CoolQ HTTP API支持的消息格式，帮助开发者更好地理解和运用这些格式。

消息格式概述

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

1. 字符串格式：传统的消息表示方式，兼容原生酷Q的消息格式
2. 数组格式：结构化更强的消息表示方式，便于程序处理

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

• 发送消息时
• 接收消息上报时
• 快速回复消息时

字符串格式详解

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

特点

• 兼容性好，直接兼容酷Q原生消息
• 多媒体内容使用CQ码表示
• 需要处理特殊字符转义

CQ码结构

CQ码的基本形式为：[CQ:type,key=value,...]

示例：

• 图片：[CQ:image,file=123.jpg]
• 表情：[CQ:face,id=123]

转义规则

由于CQ码使用了特殊字符，普通文本中的这些字符需要转义：

• [ → [
• ] → ]
• & → &
• , → ,

消息段（广义CQ码）概念

为了支持数组格式，引入了"消息段"的概念，它是对传统CQ码的扩展和结构化表示。

消息段结构

每个消息段是一个JSON对象，包含：

• type：消息类型，对应CQ码的功能名
• data：消息数据，对应CQ码的参数

示例：

{
    "type": "image",
    "data": {
        "file": "123.jpg",
        "url": "http://example.com/123.jpg"
    }
}

特殊文本消息段

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

{
    "type": "text",
    "data": {
        "text": "这是一段纯文本"
    }
}

数组格式详解

数组格式由多个消息段组成，提供了更结构化的消息表示方式。

优势

• 结构化更强，便于程序解析和处理
• 无需处理字符转义问题
• 可读性更好

转换示例

字符串格式：

[第一部分][CQ:image,file=123.jpg]图片之后的部分，表情：[CQ:face,id=123]

对应的数组格式：

[
    {"type":"text","data":{"text":"[第一部分]"}},
    {"type":"image","data":{"file":"123.jpg"}},
    {"type":"text","data":{"text":"图片之后的部分，表情："}},
    {"type":"face","data":{"id":"123"}}
]

格式选择建议

在实际开发中，可以根据场景选择合适的格式：

1. 字符串格式适用场景：

   • 需要兼容旧代码
   • 处理简单文本消息
   • 对性能要求较高的场景

2. 数组格式适用场景：

   • 需要精确处理消息各部分
   • 开发新功能
   • 需要更好的可读性和可维护性

注意事项

1. 所有消息段中的参数值都应以字符串形式表示
2. 上报消息的格式由配置文件中的post_message_format参数决定
3. 数组格式中的消息段顺序很重要，会影响最终消息的展示顺序

总结

CoolQ HTTP API提供的两种消息格式各有优势，开发者可以根据实际需求灵活选择。字符串格式兼容性好，适合简单场景；数组格式结构化强，适合复杂消息处理。理解这两种格式的特点和转换关系，将有助于开发出更健壮的机器人应用。