CoolQ HTTP API 消息格式深度解析

CoolQ HTTP API 消息格式深度解析

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

消息格式概述

在CoolQ HTTP API中，消息处理是核心功能之一。该系统全面支持两种消息格式：字符串(string)和数组(array)格式。这两种格式可以用于发送消息、上报事件以及快速回复三种场景。

两种消息格式对比

字符串格式

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

1. 所有内容（包括文本和多媒体）都包含在一个字符串中
2. 多媒体内容使用CQ码表示，例如[CQ:image,file=123.jpg]
3. 需要转义特殊字符，如[、]等
4. 结构紧凑但解析复杂

数组格式

数组格式是更现代化的消息表示方式：

1. 消息被分解为多个独立的消息段
2. 每个消息段明确指定类型和数据
3. 无需转义特殊字符
4. 结构清晰但占用空间稍大

消息段详解

消息段(Message Segment)是数组格式的基础单元，它扩展了传统CQ码的概念：

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

特殊消息段类型

1. text类型：表示纯文本内容

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

2. 多媒体类型：如图片、表情等

   {
       "type": "image",
       "data": {
           "file": "123.jpg"
       }
   }
   

格式转换原理

字符串格式和数组格式可以相互转换：

1. 字符串转数组：

   • 解析字符串中的CQ码
   • 将纯文本部分转为text类型消息段
   • 将CQ码转为对应类型的消息段

2. 数组转字符串：

   • 将text类型消息段直接输出为文本
   • 将其他类型消息段转为CQ码
   • 拼接所有部分

实际应用示例

发送混合消息

传统字符串格式：

[提示]请查看图片：[CQ:image,file=example.jpg]

对应的数组格式：

[
    {
        "type": "text",
        "data": {
            "text": "[提示]请查看图片："
        }
    },
    {
        "type": "image",
        "data": {
            "file": "example.jpg"
        }
    }
]

配置建议

1. API调用：建议优先使用数组格式，结构更清晰
2. 事件上报：根据性能需求选择，字符串格式更节省带宽
3. 开发调试：数组格式更易于阅读和调试

性能与兼容性考虑

1. 字符串格式：

   • 兼容性最好
   • 处理效率高
   • 但转义逻辑复杂

2. 数组格式：

   • 处理更直观
   • 扩展性更好
   • 但需要额外解析

最佳实践

1. 在需要处理复杂消息内容时，建议在应用内部使用数组格式
2. 与现有系统集成时，可考虑使用字符串格式保持兼容
3. 开发新功能时，优先考虑数组格式以获得更好的可维护性

通过深入理解这两种消息格式的特点和转换原理，开发者可以更灵活地在不同场景中选择最适合的消息处理方式。

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