01. 连接与消息协议

1. 连接建立

1.1 WebSocket 地址

ws://[host]:[port]/ws?token=[auth_token]

1.2 连接示例 (JavaScript)

const token = 'your_auth_token'; 
const wsUrl = `ws://localhost:8060/ws?token=${token}`;
const ws = new WebSocket(wsUrl);

ws.onopen = (e) => console.log('✅ 连接已建立');
ws.onmessage = (e) => console.log('📩 收到消息:', JSON.parse(e.data));

2. 消息协议格式

2.1 基础格式 (JSON)

{
  "cmd": "command_type",
  "data": {}
}

2.2 完整命令类型清单

服务器支持 数字命令 (CmdEnum) 和 字符串命令 (SocketConstant) 两种方式。

2.2.1 系统指令 (数字类型)

命令名称	指令值 (cmd)	说明
SYS_PING	0	心跳检测
SUCCEED	1	操作成功响应 / 连接建立成功回执
USER_LIST	100001	获取当前用户的会话/在线用户列表
SEND_MSG	100002	通用消息发送 (DataMsg 格式)

2.2.2 业务指令 (字符串类型)

命令名称	指令值 (cmd)	说明
subscribe	"subscribe"	订阅特定频道/话题
unsubscribe	"unsubscribe"	取消订阅频道
join_group	"join_group"	加入群组聊天
leave_group	"leave_group"	离开群组聊天
get_online_users	"get_online_users"	获取当前所有在线用户列表
send_private_msg	"send_private_msg"	发送私聊消息 (推荐)
send_group_msg	"send_group_msg"	发送群聊消息 (推荐)

---

3. 基础消息收发流程示例

3.1 心跳检测 (SYS_PING)

请求：

ws.send(JSON.stringify({ 
    "cmd": 0, 
    "data": "ping" 
}));

响应：

{ "cmd": 0, "data": "true" }

3.2 建立连接后的回执 (SUCCEED)

连接成功后，服务器会自动推送：

{ 
    "cmd": 1, 
    "data": "session_id_xxx" 
}

3.3 发送私聊消息 (send_private_msg)

请求：

ws.send(JSON.stringify({
    "cmd": "send_private_msg",
    "data": {
        "receiverId": "456",
        "content": "你好，这是一条私聊消息",
        "contentType": "text" 
    }
}));

响应：

{ "cmd": 1, "data": "私聊消息发送成功" }

3.4 获取活跃会话列表 (USER_LIST)

说明：拉取当前用户的“最近联系人/聊天室”列表。

请求：

ws.send(JSON.stringify({ "cmd": 100001, "data": "" }));

响应：

{
    "cmd": 100001,
    "data": [
        {
            "chatRoomId": "0",
            "chatRoomName": "MMS-AI客服",
            "chatRoomType": "SYSTEM",
            "msgInfoList": [...]
        }
    ]
}

3.5 通用发送指令 (SEND_MSG)

说明：底层通用的消息发送格式。

请求：

ws.send(JSON.stringify({
    "cmd": 100002,
    "data": JSON.stringify({
        "data": {
            "chatRoomId": "123",
            "content": "Hello World",
            "sendUser": { "token": "your_token" }
        }
    })
}));

3.6 订阅/取消订阅频道 (subscribe/unsubscribe)

说明：用于监听特定的话题或频道消息。

订阅：

ws.send(JSON.stringify({
    "cmd": "subscribe",
    "data": JSON.stringify({ "channel": "news_topic" })
}));

取消订阅：

ws.send(JSON.stringify({
    "cmd": "unsubscribe",
    "data": JSON.stringify({ "channel": "news_topic" })
}));

3.7 加入/离开群组 (join_group/leave_group)

说明：进入或退出多人聊天室。

加入：

ws.send(JSON.stringify({
    "cmd": "join_group",
    "data": JSON.stringify({ "chatRoomId": "group_888" })
}));

离开：

ws.send(JSON.stringify({
    "cmd": "leave_group",
    "data": JSON.stringify({ "chatRoomId": "group_888" })
}));

3.8 获取全平台在线用户 (get_online_users)

说明：获取当前所有连接了 WebSocket 的用户 ID。

请求：

ws.send(JSON.stringify({
    "cmd": "get_online_users",
    "data": ""
}));

3.9 发送群聊消息 (send_group_msg)

说明：向指定聊天室发送多人可见消息。

请求：

ws.send(JSON.stringify({
    "cmd": "send_group_msg",
    "data": JSON.stringify({
        "chatRoomId": "group_888",
        "content": "大家好，我是新人",
        "contentType": "text"
    })
}));