WuKongIM即时通讯协议详解

协议概述

WuKongIM是一款高效、可靠的即时通讯协议，专为现代即时通讯应用设计。该协议采用二进制格式，具有结构紧凑、传输效率高、安全性好等特点。本文将深入解析WuKongIM协议的各个组成部分，帮助开发者更好地理解和实现该协议。

协议结构

WuKongIM协议采用分层设计，每个控制报文由三部分组成：

1. 固定报头(Fixed Header)：2字节，包含报文类型和标志位
2. 可变报头(Variable Header)：长度可变，根据报文类型不同而不同
3. 有效载荷(Payload)：实际传输的数据内容

这种分层设计使得协议既保持了灵活性，又能保证高效的传输效率。

固定报头详解

固定报头是每个控制报文都必须包含的部分，长度为2字节，结构如下：

第1字节

• 高4位(bit7-bit4)：控制报文类型
• 低4位(bit3-bit0)：标志位

第2字节

• 剩余长度(Remaining Length)，表示可变报头和有效载荷的总长度

控制报文类型

WuKongIM定义了10种控制报文类型：

类型名称	值	描述
Reserved	0	保留位
CONNECT	1	客户端连接请求(c2s)
CONNACK	2	服务端连接确认(s2c)
SEND	3	发送消息(c2s)
SENDACK	4	消息发送确认(s2c)
RECVEIVED	5	接收消息(s2c)
REVACK	6	接收消息确认(c2s)
PING	7	心跳请求
PONG	8	心跳响应
DISCONNECT	9	断开连接请求

标志位

标志位占用4个bit，含义如下：

标志位名称	描述
DUP	是否是重复消息(客户端重发时设为1)
SyncOnce	是否只同步一次(多设备场景下使用)
RedDot	客户端收到消息是否显示红点
NoPersist	是否不存储此消息

剩余长度编码

WuKongIM采用变长编码表示剩余长度，最多使用4个字节：

1. 每个字节使用7位表示数值，最高位(bit7)为延续位
2. 延续位为1表示还有后续字节，为0表示这是最后一个字节
3. 数值计算采用小端序，第一个字节是最低位

这种编码方式可以高效地表示0-256MB的数据长度。

可变报头和有效载荷

可变报头的内容根据报文类型不同而变化，主要包含一些控制信息和元数据。有效载荷则是实际传输的消息内容。

主要报文类型详解

1. CONNECT - 连接请求

客户端发起连接时发送，包含以下字段：

• Protocol Version：协议版本号
• UID：用户ID
• Token：认证令牌
• Client Key：客户端DH公钥(Base64编码)
• Device Flag：设备标识(用于同账号互踢)
• Device ID：设备唯一ID
• Client Timestamp：客户端时间戳(13位毫秒)

2. CONNACK - 连接确认

服务端响应连接请求，包含：

• Server Key：服务端DH公钥
• Salt：安全码
• Time Diff：客户端与服务端时间差(毫秒)
• Reason Code：连接结果状态码

3. SEND - 发送消息

客户端发送消息时使用，主要字段：

• Setting：消息设置(1字节)
• Msg Key：消息验证密钥
• Client Seq：客户端消息序列号
• Client Msg No：客户端消息唯一标识(去重用)
• Channel Id：频道ID
• Channel Type：频道类型(1:个人 2:群组)
• Payload：加密的消息内容

4. SENDACK - 发送确认

服务端确认消息接收，包含：

• Client Seq：客户端消息序列号
• Message ID：服务端分配的消息ID(全局唯一)
• Message Seq：消息序号(用户唯一，有序递增)
• Reason Code：发送结果状态码

5. RECV - 接收消息

服务端向客户端推送消息，字段包括：

• Setting：消息设置
• Msg Key：消息验证密钥
• Message ID：服务端消息ID
• Message Seq：消息序号
• Client Msg No：客户端消息唯一标识
• Message Timestamp：服务器时间戳(10位秒)
• Channel ID/Type：频道信息
• From UID：发送者ID
• Payload：加密的消息内容

6. RECVACK - 接收确认

客户端确认消息接收，包含：

• Message ID：服务端消息ID
• Message Seq：消息序号

7. PING/PONG - 心跳机制

用于保持连接活跃，检测连接状态。

8. DISCONNECT - 断开连接

主动断开连接时使用，包含：

• ReasonCode：断开原因代码
• Reason：断开原因描述

消息设置

消息设置占用1字节(8bit)，目前定义如下：

位	名称	描述
7	Receipt	是否需要已读回执(1:需要)
6-0	Reserved	保留位

消息内容格式建议

WuKongIM推荐使用JSON格式组织消息内容，支持多种消息类型：

基础消息类型

1. 文本消息

{
    "type": 1,
    "content": "消息内容"
}

2. 图片消息

{
    "type": 2,
    "url": "图片URL",
    "width": 200,
    "height": 300
}

3. 语音消息

{
    "type": 4,
    "url": "语音URL",
    "timeTrad": 10
}

高级功能

1. @提及功能

{
    "type": 1,
    "content": "消息内容",
    "mention": {
        "all": 0,
        "uids": ["uid1", "uid2"]
    }
}

2. 消息回复

{
    "type": 1,
    "content": "回复内容",
    "reply": {
        "message_id": "被回复消息ID",
        "from_uid": "发送者UID",
        "payload": {}  // 被回复消息内容
    }
}

3. 命令消息

{
    "type": 99,
    "cmd": "commandName",
    "param": {}
}

系统消息规范

系统消息(type≥1000)用于通知类信息，如群组操作等：

1. 创建群组

{
    "type": 1001,
    "creator": "创建者UID",
    "content": "{0}创建了群组",
    "extra": [{"uid":"xxx","name":"张三"}]
}

2. 群成员变动

{
    "type": 1002,
    "content": "{0}邀请了{1}加入群组",
    "extra": [{"uid":"创建者UID","name":"张三"},{"uid":"新成员UID","name":"李四"}]
}

3. 消息撤回

{
    "type": 1006,
    "message_id": "被撤回消息ID",
    "content": "{0}撤回了一条消息",
    "extra": [{"uid":"操作者UID","name":"张三"}]
}

最佳实践建议

1. 消息去重：使用Client Msg No确保消息唯一性
2. 消息顺序：依赖Message Seq保证消息有序性
3. 安全性：务必验证Msg Key防止消息篡改
4. 状态同步：合理使用SyncOnce标志优化多设备同步
5. 心跳机制：建议每30-60秒发送一次PING保持连接

通过本文的详细解析，开发者可以全面了解WuKongIM协议的设计理念和实现细节，为开发基于该协议的即时通讯应用打下坚实基础。