code/IM

Fork 0

nanxun 848e18e057 Init

2025-10-13 17:07:12 +08:00

5.4 KiB

Raw Permalink Blame History

📘 WebSocket 通讯协议设计文档

1. 概述

本协议用于实现 即时聊天（IM）系统的实时消息传输。客户端通过 WebSocket 连接后与服务器保持长连接，实现消息推送、状态同步、群聊与单聊。

支持功能：

用户登录鉴权
单聊消息发送/接收
群聊消息发送/接收
消息撤回、已读回执
心跳保活与断线重连
系统通知（好友请求、群邀请）

2. 消息传输格式

2.1 基础消息结构（JSON）

{
  "type": "MESSAGE_TYPE",
  "requestId": "string",        // 客户端生成的请求ID，便于幂等
  "from": 1001,                 // 发送者ID
  "to": 1002,                   // 接收者ID（单聊）或群ID（群聊）
  "chatType": "single",         // "single" | "group"
  "contentType": "text",        // "text" | "image" | "file" | "voice" | "system"
  "content": "消息内容或文件URL", 
  "timestamp": 1700000000       // Unix时间戳
}

2.2 常用 type 枚举

type	说明
AUTH	握手鉴权
HEARTBEAT	心跳保活
MESSAGE	普通聊天消息（单聊/群聊）
MESSAGE_ACK	消息已读/送达回执
MESSAGE_RECALL	消息撤回
FRIEND_REQUEST	好友申请通知
GROUP_INVITE	群邀请通知
SYSTEM_NOTICE	系统公告/通知
ERROR	错误消息

3. 握手与鉴权

3.1 客户端连接

ws://example.com/ws?token=xxxx

客户端通过 Token 鉴权
服务器验证 Token 后，返回 AUTH_SUCCESS 或 AUTH_FAIL

3.2 服务端响应示例

成功：

{
  "type": "AUTH",
  "status": "success",
  "userId": 1001,
  "timestamp": 1700000000
}

失败：

{
  "type": "AUTH",
  "status": "fail",
  "code": 1006,
  "message": "Token无效或过期"
}

4. 心跳机制

4.1 客户端发送

{
  "type": "HEARTBEAT",
  "timestamp": 1700000000
}

4.2 服务器响应

{
  "type": "HEARTBEAT",
  "timestamp": 1700000000
}

客户端：每隔 30 秒发送一次心跳
服务器：若 2 倍心跳时间未收到消息，则断开连接

5. 消息传输

5.1 单聊消息

客户端发送：

{
  "type": "MESSAGE",
  "requestId": "uuid-001",
  "from": 1001,
  "to": 1002,
  "chatType": "single",
  "contentType": "text",
  "content": "你好",
  "timestamp": 1700000000
}

服务器推送给接收者：

{
  "type": "MESSAGE",
  "messageId": 50001,
  "from": 1001,
  "to": 1002,
  "chatType": "single",
  "contentType": "text",
  "content": "你好",
  "timestamp": 1700000000
}

5.2 群聊消息

{
  "type": "MESSAGE",
  "requestId": "uuid-002",
  "from": 1001,
  "to": 3001,               // 群ID
  "chatType": "group",
  "contentType": "image",
  "content": "http://img.example.com/xxx.jpg",
  "timestamp": 1700000000
}

服务器会 推送到群成员列表（除了自己）。

5.3 消息回执（MESSAGE_ACK）

客户端收到消息后发送：

{
  "type": "MESSAGE_ACK",
  "messageId": 50001,
  "from": 1002,
  "to": 1001,
  "chatType": "single",
  "status": "read",
  "timestamp": 1700000000
}

服务器更新消息状态，并可推送给发送方。

5.4 消息撤回（MESSAGE_RECALL）

客户端请求撤回消息：

{
  "type": "MESSAGE_RECALL",
  "messageId": 50001,
  "from": 1001,
  "to": 1002,
  "chatType": "single",
  "timestamp": 1700000010
}

服务器验证是否允许撤回（时间限制、权限等），允许则推送给接收方：

{
  "type": "MESSAGE_RECALL",
  "messageId": 50001,
  "from": 1001,
  "chatType": "single",
  "status": "success",
  "timestamp": 1700000010
}

6. 好友 / 群邀请通知

6.1 好友申请（FRIEND_REQUEST）

{
  "type": "FRIEND_REQUEST",
  "requestId": "uuid-003",
  "from": 1001,
  "to": 1002,
  "content": "加个好友吧",
  "timestamp": 1700000020
}

6.2 群邀请（GROUP_INVITE）

{
  "type": "GROUP_INVITE",
  "inviteId": "uuid-004",
  "groupId": 3001,
  "inviter": 1001,
  "invitee": 1003,
  "content": "邀请你加入群聊",
  "timestamp": 1700000030
}

7. 错误处理（ERROR）

{
  "type": "ERROR",
  "code": 2300,
  "message": "消息发送失败",
  "requestId": "uuid-001",
  "timestamp": 1700000040
}

code 对应响应 Code 规范
requestId 可帮助客户端确认失败的具体请求

8. 断线重连

客户端断线后，尝试每隔 5 秒重连一次
重连成功后，重新发送 AUTH 消息进行鉴权
重连后可请求 未读消息同步（message 表或 Redis 缓存）

9. 附录：contentType 示例

contentType	content 示例	描述
text	"你好"	文本消息
image	"http://img.example.com/xxx.jpg"	图片 URL
file	"http://file.example.com/xxx.pdf"	文件 URL + 文件名
voice	"http://audio.example.com/xxx.mp3"	语音 URL + 时长
system	"用户xxx加入群"	系统消息

5.4 KiB Raw Permalink Blame History Unescape Escape