CoolQ HTTP API 消息格式深度解析

CoolQ HTTP API 消息格式深度解析

coolq-http-api 项目地址: https://gitcode.com/gh_mirrors/coo/coolq-http-api

消息格式概述

CoolQ HTTP API 在处理消息时提供了两种灵活的格式：字符串格式和数组格式。这两种格式可以用于消息发送、事件上报和快速回复三种场景。理解这两种格式的特点和使用场景，对于开发者构建高效的机器人应用至关重要。

两种消息格式对比

字符串格式

字符串格式是 CoolQ 原生支持的传统消息格式，特点如下：

1. 单一字符串结构：所有消息内容（包括文本和多媒体）都包含在一个字符串中
2. CQ码嵌入：多媒体内容通过特殊格式的CQ码表示
3. 转义需求：需要对特殊字符进行转义处理

示例：

[提示]这是一张图片：[CQ:image,file=example.jpg]

数组格式

数组格式是更现代化的消息表示方式，特点如下：

1. 结构化表示：消息被分解为多个独立的消息段
2. 类型明确：每个消息段都有明确的类型标识
3. 无需转义：每个字段的值都是真实值，不需要额外转义
4. 扩展性强：便于程序处理和扩展

示例（JSON格式）：

[
    {
        "type": "text",
        "data": {"text": "[提示]这是一张图片："}
    },
    {
        "type": "image",
        "data": {"file": "example.jpg"}
    }
]

消息段详解

消息段（Message Segment）是数组格式的基本组成单元，它是对传统CQ码的扩展和规范化表示。

消息段结构

每个消息段包含两个主要部分：

1. type：标识消息类型，如"text"表示文本，"image"表示图片
2. data：包含消息具体参数的对象，所有值都以字符串形式表示

常见消息段类型

1. 文本消息段：

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

2. 图片消息段：

   {
       "type": "image",
       "data": {
           "file": "图片文件名",
           "url": "图片URL(可选)"
       }
   }
   

3. 表情消息段：

   {
       "type": "face",
       "data": {"id": "表情ID"}
   }
   

格式转换原理

理解字符串格式和数组格式之间的转换规则，有助于开发者灵活处理消息。

字符串转数组

转换过程：

1. 解析字符串中的CQ码和纯文本部分
2. 为每个部分创建对应的消息段
3. 将所有消息段按顺序组成数组

数组转字符串

转换过程：

1. 遍历数组中的每个消息段
2. 将消息段转换为对应的CQ码或纯文本
3. 拼接所有转换结果为一个完整字符串

实际应用建议

何时使用字符串格式

1. 处理简单的纯文本消息
2. 需要与旧系统兼容时
3. 手动构造测试消息时

何时使用数组格式

1. 需要处理复杂多媒体消息时
2. 程序化生成消息内容时
3. 需要精确控制消息各部分时

性能考虑

1. 简单消息使用字符串格式更高效
2. 复杂消息使用数组格式更易维护
3. 频繁处理消息时，数组格式通常性能更好

最佳实践示例

发送混合消息

{
    "message": [
        {"type": "text", "data": {"text": "今日天气："}},
        {"type": "image", "data": {"file": "weather.png"}},
        {"type": "text", "data": {"text": "记得带伞哦！"}},
        {"type": "face", "data": {"id": "14"}}
    ]
}

快速回复消息

{
    "reply": [
        {"type": "text", "data": {"text": "已收到您的反馈："}},
        {"type": "text", "data": {"text": "我们会尽快处理！"}}
    ]
}

总结

CoolQ HTTP API 提供的两种消息格式各有优势，开发者应根据实际场景选择合适的格式。字符串格式适合简单场景和兼容性需求，而数组格式则提供了更好的结构化和扩展性。理解消息段的原理和转换规则，能够帮助开发者更高效地构建机器人应用。

coolq-http-api 项目地址: https://gitcode.com/gh_mirrors/coo/coolq-http-api