通讯协议文档

本通讯协议旨在为即时通讯系统提供一套全面、可靠的消息传输标准。协议支持多种登录方式、消息类型及群聊功能，并包含完善的鉴权与消息重发机制，确保消息的安全与可靠传递。

功能概述

本通讯协议支持以下功能：

确认（ACK）、重发、消息序列 管理。
匿名登录、用户名密码登录 和 Token 登录。
支持发送多种类型的消息：文本（Text）、图片（Image）、音频（Audio）、视频（Video）、新闻（News）、Markdown。
群聊功能：创建群、解散群、邀请加入群、加入群、退出群、屏蔽群、群发消息。
鉴权机制：在发送消息等相关操作中需要携带 token 进行鉴权。

消息格式

所有消息均采用统一的 JSON/Binary 结构，确保不同类型的消息能够被一致地处理和解析。

消息重发机制

为了确保消息的可靠传输，本协议采用消息序列号与确认（ACK）机制。

消息序列号（sequence）：每个消息都有唯一的序列号，用于跟踪消息的发送和接收。
确认字段（ack）：用于确认收到特定序列号的消息。如果发送方在一定时间内未收到确认，则会重发该消息。

登录方式

协议支持多种登录方式，以满足不同场景下的需求：

匿名登录：
- 在登录请求中，将 anonymous 字段设置为 true，并提供 loginname 进行匿名登录。
- 示例：
  json
```
{
  "username": "guest",
  "anonymous": true
}
```
  1
  2
  3
  4
用户名密码登录：
- 提供 username 和 password 字段进行验证。
- 示例：
  json
```
{
  "username": "user123",
  "password": "securepassword"
}
```
  1
  2
  3
  4
Token 登录：
- 提供 token 字段进行验证，适用于已经获取过 Token 的场景。
- 示例：
  json
```
{
  "token": "abcdef123456"
}
```
  1
  2
  3

注意：在登录请求中，username 和 password 与 token 仅需传递一种即可。

群聊功能

本协议支持全面的群聊功能，具体包括：

创建群：用户可创建新群组，指定群名称、初始成员及群描述。
解散群：群主或有权限的成员可解散群组。
邀请加入群：群主或有权限的成员可邀请其他用户加入群组。
加入群：用户可通过邀请或申请方式加入群组。
退出群：群成员可主动退出群组。
屏蔽群：群成员可选择屏蔽某个群组的消息通知。
群发消息：用户可向群组发送多种类型的消息。

上述每项功能均通过相应的请求与响应消息进行操作和确认，确保群聊功能的可靠性与用户体验。

消息通讯协议

通用消息结构

所有的消息均遵循以下通用结构：

json

{
  "cmd": "命令码",
  "sequence": "消息序列号 (Long类型)",
  "ack": "确认的消息序列号 (Long类型，可选)",
  "from": "发送方ID",
  "to": "接收方ID",
  "token": "鉴权令牌 (String类型，可选)",
  "timestamp": "消息创建时间 (Long类型, UTC时间戳)",
  "body": {
    // 根据cmd不同，body内容不同
  }
}

cmd：命令码，表示消息类型。
sequence：消息序列号，用于消息的唯一标识和重发机制。
ack：可选字段，用于确认收到特定序列号的消息。
from 和 to：发送方和接收方的 ID。
token：用于鉴权的令牌，部分消息类型为必填项。
timestamp：消息创建的时间戳，采用 System.currentTimeMillis() 方法生成，自 1970 年 1 月 1 日 00:00:00 UTC 起的毫秒数。
body：消息主体，根据不同的 cmd 类型而变化。

时间戳说明

定义为自 1970 年 1 月 1 日 00:00:00 UTC（协调世界时）起至当前时刻的毫秒数。这是一个绝对时间戳，表示的是统一的 UTC 时间，与系统的本地时区设置无关。

具体命令

以下是具体的命令码及其对应的消息结构。

0. 错误信息

命令码：COMMAND_ERROR (0)

json

{
  "cmd": 0,
  "ack": 1234567894,
  "message": "错误描述信息"
}

说明：用于传递错误信息，ack 字段指向相关联的消息序列号。

1. 确认消息（ACK）

命令码：COMMAND_ACK (1)

json

{
  "cmd": 1,
  "ack": 1234567890,
  "timestamp": 1725338896411
}

说明：用于确认已收到特定序列号的消息。

3. 登录请求消息

命令码：COMMAND_LOGIN_REQ (3)

json

{
  "cmd": 3,
  "sequence": 1234567894,
  "timestamp": 1725338896811,
  "body": {
    "username": "用户名",
    "password": "密码",
    "token": "令牌",
    "anonymous": true // 是否匿名登录，默认为false(可选)
  }
}

说明：客户端发送的登录请求。根据登录方式，body 中的字段会有所不同。

4. 登录响应消息

命令码：COMMAND_LOGIN_RESP (4)

json

{
  "cmd": 4,
  "ack": 1234567894,
  "code": 1, // 1: 成功, 其他: 错误代码
  "message": "描述信息",
  "body": {
    "userId": "1"
  }
}

说明：服务器对登录请求的响应，code 表示状态，body 中包含用户 ID。

5. 鉴权请求消息

命令码：COMMAND_AUTH_REQ (5)

json

{
  "cmd": 5,
  "sequence": 1234567892,
  "timestamp": 1725338896611,
  "token": "校验码"
}

说明：用于验证用户身份的请求消息，需携带有效的 token。

6. 鉴权响应消息

命令码：COMMAND_AUTH_RESP (6)

json

{
  "cmd": 6,
  "ack": 1234567892,
  "timestamp": 1725338896711,
  "code": 1, // 1: 成功, 其他: 错误代码
  "message": "描述信息"
}

说明：服务器对鉴权请求的响应，code 表示鉴权结果。

7. 心跳请求消息

命令码：COMMAND_HEARTBEAT_REQ (7)

json

{
  "cmd": 7,
  "sequence": 1234567896,
  "timestamp": 1725338897011
}

说明：客户端发送的心跳请求，仅包含 cmd、sequence 和 timestamp 三个字段，用于维持连接活跃。

8. 心跳响应消息

命令码：COMMAND_HEARTBEAT_RESP (8)

json

{
  "cmd": 8,
  "ack": 1234567896,
  "timestamp": 1725338897011,
  "code": 1, // 1: 成功, 其他: 错误代码
  "message": "描述信息"
}

说明：服务器对心跳请求的响应，ack 对应客户端发送的 sequence。

备注：根据具体业务实现，有时 cmd 可能复用为 1（ACK 消息）以简化响应。

9. 退出请求消息

命令码：COMMAND_CLOSE_REQ (9)

json

{
  "cmd": 9,
  "sequence": 1234567897,
  "from": "客户端ID",
  "token": "鉴权令牌",
  "timestamp": 1725338897111
}

说明：客户端发送的退出请求，用于断开与服务器的连接。

10. 退出响应消息

命令码：COMMAND_CLOSE_RESP (10)

json

{
  "cmd": 10,
  "ack": 1234567897,
  "timestamp": 1725338897111,
  "code": 1, // 1: 成功, 其他: 错误代码
  "message": "描述信息"
}

说明：服务器对退出请求的响应，确认客户端已成功退出。

11. 聊天消息请求

命令码：COMMAND_CHAT_REQ (11)
发送消息

json

{
  "cmd": 11,
  "sequence": 1234567890,
  "to": "接收方ID",
  "timestamp": 1725338896411,
  "body": {
    "msgType": "消息类型 (text、image、audio、video、news、markdown)",
    "content": {
      // 根据msgType不同，content结构不同
    }
  }
}

接收消息

json

{
  "cmd": 11,
  "timestamp": 1725338896411,
  "sequence": 1234567890,
  "from": "发送方Id",
  "to": "接收方id",
  "id": "雪花id", // 服务器生成
  "body": {
    "msgType": "消息类型 (text、image、audio、video、news、markdown)",
    "content": {
      // 根据msgType不同，content结构不同
    }
  }
}

说明：
- 客户端发送聊天消息时，指定接收方 ID 及消息内容。
- 服务器转发消息时，包含发送方 ID、接收方 ID 及服务器生成的唯一消息 ID（雪花 ID）。

根据不同的 msgType，消息内容（content）的结构有所不同：

文本消息（text）

json

"content": {
    "text": "文本内容"
}

图片消息（image）

json

"content": {
    "url": "图片URL",
    "width": 800,
    "height": 600,
    "format": "png"
}

音频消息（audio）

json

"content": {
    "url": "音频URL",
    "duration": 60, // 秒
    "format": "mp4"
}

视频消息（video）

json

"content": {
    "url": "视频URL",
    "duration": 60, // 秒
    "thumbnail": "缩略图URL",
    "format": "mp4"
}

新闻消息（news）

json

"content": {
    "title": "新闻标题",
    "description": "新闻描述",
    "url": "新闻链接",
    "image": "新闻图片URL"
}

Markdown 消息（markdown）

json

"content": {
    "markdown": "Markdown格式的文本"
}

12. 聊天消息响应

命令码：COMMAND_CHAT_RESP (12)

json

{
  "cmd": 12,
  "timestamp": 1725338896411,
  "from": "发送方Id",
  "to": "接收方Id",
  "ack": 1234567890,
  "id": "雪花id", // 服务器生成
  "code": 1, // 1: 成功, 其他: 错误代码
  "message": "描述信息"
}

字段说明：
- ack：确认的消息序列 ID，用于消息追踪和确认。
- code：消息状态码，具体含义如下：
  - 0: 消息发送失败。
  - 1: 消息已成功入库。
  - 2: 消息已从服务器成功发送。
  - 3: 消息已成功到达客户端。
  - 4: 目标用户已读该消息。
  - 5: 目标用户已屏蔽该用户。
- id：由服务器在消息入库后生成的唯一雪花 ID。
消息流程说明：
1. 服务器响应：服务器在收到消息后，立即返回 COMMAND_CHAT_RESP 消息，用于确认该消息是否成功入库或已从服务器发送。
2. 客户端响应：客户端在收到消息后，需要向服务器发送 COMMAND_CHAT_RESP，以确认消息已成功到达客户端。
3. 超时与重发机制：如果服务器未能及时收到客户端的 COMMAND_CHAT_RESP 响应，将认为消息未送达，并启动定时重发机制，确保消息的可靠送达。

13. 已读请求消息

命令码：COMMAND_MESSAGE_READ_REQ (13)

json

{
  "cmd": 13,
  "timestamp": 1725338896411,
  "sequence": 1234567890,
  "from": "2",
  "to": "1",
  "id": "451987138345680896",
  "code": 1
}

说明：用于通知服务器某条消息已被阅读。包含消息 ID 及相关信息。

14. 已读响应消息

命令码：COMMAND_MESSAGE_READ_RESP (14)

json

{
  "cmd": 14,
  "ack": 1234567890,
  "timestamp": 1111111111,
  "code": 1
}

说明：服务器对已读请求的响应，确认已收到已读通知。

15. 撤回消息请求

命令码：COMMAND_RECALL_MSG_REQ (15)

json

{
  "cmd": 15,
  "timestamp": 1725338899011,
  "sequence": 1234567915,
  "from": "用户ID",
  "id": "451987138345680896" // 撤回的消息ID
}

说明：用户请求撤回某条已发送的消息，需提供消息 ID。

16. 撤回消息响应

命令码：COMMAND_RECALL_MSG_RESP (16)

json

{
  "cmd": 16,
  "ack": 1234567915,
  "timestamp": 1725338899111,
  "code": 1,
  "message": "描述信息"
}

说明：服务器对撤回消息请求的响应，确认撤回操作是否成功。

17. 消息转发请求

命令码：COMMAND_FORWARD_MSG_REQ (17)

json

{
  "cmd": 17,
  "timestamp": 1725338899211,
  "sequence": 1234567916,
  "from": "用户ID",
  "body": {
    "to": ["接收方ID1", "接收方ID2"] // 支持多目标
  },
  "originalMsgId": "原始消息ID" // 需转发的消息ID
}

说明：支持将指定消息转发给其他用户或群组，to 字段支持多个目标。

18. 消息转发响应

命令码：COMMAND_FORWARD_MSG_RESP (18)

json

{
  "cmd": 18,
  "ack": 1234567916,
  "timestamp": 1725338899211,
  "code": 1,
  "message": "描述信息"
}

说明：服务器对消息转发请求的响应，确认转发操作是否成功。

19. 获取用户信息请求消息

命令码：COMMAND_GET_USER_REQ (19)

json

{
  "cmd": 19,
  "sequence": 1234567898,
  "timestamp": 1725338897211,
  "body": {
    "userId": "用户ID", // type为0时必填
    "groupId": "组ID", // type为1时必填
    "type": 0 // 0: 获取好友信息, 1: 获取指定组信息, 2: 获取其他类型信息
  }
}

说明：用于请求获取用户或群组的信息，根据 type 字段决定获取的具体信息类型。

20. 获取用户信息响应消息

命令码：COMMAND_GET_USER_RESP (20)

json

{
  "cmd": 20,
  "ack": 1234567898,
  "timestamp": 1725338897311,
  "body": {
    "users": [
      {
        "userId": "用户ID",
        "username": "用户名",
        "nickname": "昵称",
        "avatar": "头像URL"
        // 更多用户信息字段
      }
      // 可包含更多用户信息
    ]
  }
}

说明：服务器对获取用户信息请求的响应，body 中包含所请求的用户或群组详细信息。

21. 创建群请求消息

命令码：COMMAND_CREATE_GROUP_REQ (21)

json

{
  "cmd": 21,
  "sequence": 1234567900,
  "timestamp": 1725338897411,
  "body": {
    "groupName": "群名称",
    "members": ["成员ID1", "成员ID2"], // 可选，初始成员列表
    "description": "群描述"
  }
}

说明：用户请求创建一个新群组，可以指定初始成员列表及群组描述。

22. 创建群响应消息

命令码：COMMAND_CREATE_GROUP_RESP (22)

json

{
  "cmd": 22,
  "ack": 1234567900,
  "timestamp": 1725338897511,
  "code": 1, // 1: 成功, 其他: 错误代码
  "message": "描述信息",
  "body": {
    "groupId": "新创建的群ID"
  }
}

说明：服务器对创建群请求的响应，返回新创建的群 ID。

23. 解散群请求消息

命令码：COMMAND_DISBAND_GROUP_REQ (23)

json

{
  "cmd": 23,
  "sequence": 1234567902,
  "timestamp": 1725338897611,
  "body": {
    "groupId": "群ID",
    "name": "群主用户名" // 可选，用于验证操作权限
  }
}

说明：群主或有权限的用户请求解散指定群组。

24. 解散群响应消息

命令码：COMMAND_DISBAND_GROUP_RESP (24)

json

{
  "cmd": 24,
  "ack": 1234567902,
  "timestamp": 1725338897711,
  "code": 1, // 1: 成功, 其他: 错误代码
  "message": "描述信息"
}

说明：服务器对解散群请求的响应，确认群组是否成功解散。

25. 邀请加入群请求消息

命令码：COMMAND_INVITE_TO_GROUP_REQ (25)

json

{
  "cmd": 25,
  "sequence": 1234567904,
  "timestamp": 1725338897811,
  "body": {
    "groupId": "群ID",
    "invitees": ["被邀请者ID1", "被邀请者ID2"]
  }
}

说明：群主或有权限的成员邀请其他用户加入群组。

26. 邀请加入群响应消息

命令码：COMMAND_INVITE_TO_GROUP_RESP (26)

json

{
  "cmd": 26,
  "ack": 1234567904,
  "timestamp": 1725338897911,
  "code": 1, // 1: 成功, 其他: 错误代码
  "message": "描述信息"
}

说明：服务器对邀请加入群请求的响应，确认邀请操作是否成功。

27. 加入群请求消息

命令码：COMMAND_JOIN_GROUP_REQ (27)

json

{
  "cmd": 27,
  "sequence": 1234567906,
  "timestamp": 1725338898011,
  "body": {
    "groupId": "群ID"
  }
}

说明：用户请求加入指定群组。

28. 加入群响应消息

命令码：COMMAND_JOIN_GROUP_RESP (28)

json

{
  "cmd": 28,
  "ack": 1234567906,
  "timestamp": 1725338898111,
  "code": 1, // 1: 成功, 其他: 错误代码
  "message": "描述信息"
}

说明：服务器对加入群请求的响应，确认加入操作是否成功。

29. 退出群请求消息

命令码：COMMAND_LEAVE_GROUP_REQ (29)

json

{
  "cmd": 29,
  "sequence": 1234567908,
  "from": "成员ID",
  "token": "鉴权令牌",
  "timestamp": 1725338898211,
  "body": {
    "groupId": "群ID"
  }
}

说明：成员请求退出指定群组，需携带有效的 token 进行鉴权。

30. 退出群响应消息

命令码：COMMAND_LEAVE_GROUP_RESP (30)

json

{
  "cmd": 30,
  "ack": 1234567908,
  "timestamp": 1725338898311,
  "code": 1, // 1: 成功, 其他: 错误代码
  "message": "描述信息"
}

说明：服务器对退出群请求的响应，确认退出操作是否成功。

31. 群发消息请求

命令码：COMMAND_GROUP_MESSAGE_REQ (31)

json

{
  "cmd": 31,
  "sequence": 1234567912,
  "groupId": "群ID",
  "timestamp": 1725338898611,
  "body": {
    "msgType": "消息类型",
    "content": {
      // 与之前的消息类型相同
    }
  }
}

说明：用户向群组发送消息，支持多种消息类型。

32. 群发消息响应

命令码：COMMAND_GROUP_MESSAGE_RESP (32)

json

{
  "cmd": 32,
  "sequence": 1234567913,
  "ack": 1234567912,
  "from": "服务器ID",
  "groupId": "发送方ID",
  "timestamp": 1725338898711,
  "code": 1,
  "message": "描述信息"
}

说明：服务器对群发消息请求的响应，确认消息是否成功发送至群组。

33. 静音用户请求消息

命令码：COMMAND_MUTE_USER_REQ (33)

json

{
  "cmd": 33,
  "sequence": 1234567910,
  "timestamp": 1725338898411,
  "body": {
    "user_id": "群ID",
    "mute": true // true: 静音, false: 取消静音
  }
}

34. 静音用户响应消息

命令码：COMMAND_MUTE_USER_RESP (34)

json

{
  "cmd": 34,
  "ack": 1234567910,
  "from": "用户id",
  "timestamp": 1725338898511,
  "code": 1,
  "message": "描述信息"
}

35. 屏蔽用户请求消息

命令码：COMMAND_BLOCK_USER_REQ (35)

json

{
  "cmd": 35,
  "sequence": 1234567910,
  "timestamp": 1725338898411,
  "body": {
    "user_id": "user id",
    "block": true // true: 屏蔽, false: 取消屏蔽
  }
}

36. 屏蔽用户响应消息

命令码：COMMAND_MUTE_USER_RESP (36)

json

{
  "cmd": 36,
  "ack": 1234567910,
  "from": "用户id",
  "timestamp": 1725338898511,
  "code": 1,
  "message": "描述信息"
}

37. 删除用户请求消息

命令码：COMMAND_DELETE_USER_REQ (37)

json

{
  "cmd": 35,
  "sequence": 1234567910,
  "timestamp": 1725338898411,
  "body": {
    "user_id": "群ID",
    "delete": true // true: 删除, false: 取消删除
  }
}

38. 删除用户响应消息

命令码：COMMAND_DELETE_USER_RESP (38)

json

{
  "cmd": 39,
  "ack": 1234567910,
  "from": "用户id",
  "timestamp": 1725338898511,
  "code": 1,
  "message": "描述信息"
}

41. 静音群请求消息

命令码：COMMAND_MUTE_GROUP_REQ (41)

json

{
  "cmd": 41,
  "sequence": 1234567910,
  "from": "成员ID",
  "timestamp": 1725338898411,
  "body": {
    "groupId": "群ID",
    "mute": true // true: 屏蔽, false: 取消屏蔽
  }
}

说明：成员请求屏蔽或取消屏蔽指定群组的消息通知。

42. 静音群响应消息

命令码：COMMAND_MUTE_GROUP_RESP (42)

json

{
  "cmd": 41,
  "ack": 1234567910,
  "from": "成员ID",
  "timestamp": 1725338898511,
  "code": 1,
  "message": "描述信息"
}

说明：服务器对屏蔽群请求的响应，确认屏蔽操作是否成功。

43. 屏蔽群请求消息

命令码：COMMAND_BLOCK_GROUP_REQ (43)

json

{
  "cmd": 43,
  "sequence": 1234567910,
  "from": "成员ID",
  "timestamp": 1725338898411,
  "body": {
    "groupId": "群ID",
    "mute": true // true: 屏蔽, false: 取消屏蔽
  }
}

说明：成员请求屏蔽或取消屏蔽指定群组的消息通知。

44. 屏蔽群响应消息

命令码：COMMAND_BLOCK_GROUP_RESP (44)

json

{
  "cmd": 44,
  "ack": 1234567910,
  "from": "成员ID",
  "timestamp": 1725338898511,
  "code": 1,
  "message": "描述信息"
}

说明：服务器对屏蔽群请求的响应，确认屏蔽操作是否成功。

附录

错误代码说明

1：操作成功。
2：认证失败或 Token 无效。
3：权限不足。
4：目标用户或群组不存在。
5：消息格式错误。
6：服务器内部错误。
7：消息未找到（用于撤回操作）。
8：操作超时。
9：其他自定义错误代码。

备注：具体错误代码的定义可根据实际业务需求进行扩展和调整。

通讯协议文档 ​

功能概述 ​

消息格式 ​

消息重发机制 ​

登录方式 ​

群聊功能 ​

消息通讯协议 ​

通用消息结构 ​

时间戳说明 ​

具体命令 ​

0. 错误信息 ​

1. 确认消息（ACK） ​

3. 登录请求消息 ​

4. 登录响应消息 ​

5. 鉴权请求消息 ​

6. 鉴权响应消息 ​

7. 心跳请求消息 ​

8. 心跳响应消息 ​

9. 退出请求消息 ​

10. 退出响应消息 ​

11. 聊天消息请求 ​

12. 聊天消息响应 ​

13. 已读请求消息 ​

14. 已读响应消息 ​

15. 撤回消息请求 ​

16. 撤回消息响应 ​

17. 消息转发请求 ​

18. 消息转发响应 ​

19. 获取用户信息请求消息 ​

20. 获取用户信息响应消息 ​

21. 创建群请求消息 ​

22. 创建群响应消息 ​

23. 解散群请求消息 ​

24. 解散群响应消息 ​

25. 邀请加入群请求消息 ​

26. 邀请加入群响应消息 ​

27. 加入群请求消息 ​

28. 加入群响应消息 ​

29. 退出群请求消息 ​

30. 退出群响应消息 ​

31. 群发消息请求 ​

32. 群发消息响应 ​

33. 静音用户请求消息 ​

34. 静音用户响应消息 ​

35. 屏蔽用户请求消息 ​

36. 屏蔽用户响应消息 ​

37. 删除用户请求消息 ​

38. 删除用户响应消息 ​

41. 静音群请求消息 ​

42. 静音群响应消息 ​

43. 屏蔽群请求消息 ​

44. 屏蔽群响应消息 ​

附录 ​

错误代码说明 ​

通讯协议文档

功能概述

消息格式

消息重发机制

登录方式

群聊功能

消息通讯协议

通用消息结构

时间戳说明

具体命令

0. 错误信息

1. 确认消息（ACK）

3. 登录请求消息

4. 登录响应消息

5. 鉴权请求消息

6. 鉴权响应消息

7. 心跳请求消息

8. 心跳响应消息

9. 退出请求消息

10. 退出响应消息

11. 聊天消息请求

12. 聊天消息响应

13. 已读请求消息

14. 已读响应消息

15. 撤回消息请求

16. 撤回消息响应

17. 消息转发请求

18. 消息转发响应

19. 获取用户信息请求消息

20. 获取用户信息响应消息

21. 创建群请求消息

22. 创建群响应消息

23. 解散群请求消息

24. 解散群响应消息

25. 邀请加入群请求消息

26. 邀请加入群响应消息

27. 加入群请求消息

28. 加入群响应消息

29. 退出群请求消息

30. 退出群响应消息

31. 群发消息请求

32. 群发消息响应

33. 静音用户请求消息

34. 静音用户响应消息

35. 屏蔽用户请求消息

36. 屏蔽用户响应消息

37. 删除用户请求消息

38. 删除用户响应消息

41. 静音群请求消息

42. 静音群响应消息

43. 屏蔽群请求消息

44. 屏蔽群响应消息

附录

错误代码说明