6cd938cfbc
- 实现了Android SDK的完整IM功能接口，包括消息、群组、好友、会话等核心功能 - 添加了消息收发、历史记录、撤回编辑等完整的消息操作能力 - 实现了群组管理功能，包括创建、成员管理、权限设置等操作 - 添加了好友关系链管理，支持添加、删除、分组等操作 - 实现了会话管理功能，包括置顶、免打扰、已读状态等 - 添加了黑名单、资料管理、搜索等辅助功能 - 补齐了批量操作接口，提升客户端操作效率 - 实现了WebSocket连接管理和事件监听机制 - 添加了离线消息同步和状态管理功能
193 行
3.3 KiB
Markdown
193 行
3.3 KiB
Markdown
# WebSocket 协议文档
|
||
|
||
XuqmGroup IM 使用 **STOMP over WebSocket** 协议进行实时消息通信。
|
||
|
||
---
|
||
|
||
## 连接地址
|
||
|
||
| 环境 | 地址 |
|
||
|------|------|
|
||
| 演示环境 | `wss://dev.xuqinmin.com/ws/im` |
|
||
| 生产环境 | 由租户平台分配 |
|
||
|
||
连接时需携带 `token` 参数：
|
||
|
||
```
|
||
wss://dev.xuqinmin.com/ws/im?token={userSig}
|
||
```
|
||
|
||
---
|
||
|
||
## 心跳机制
|
||
|
||
客户端在 STOMP CONNECT 帧中声明心跳：
|
||
|
||
```
|
||
CONNECT
|
||
accept-version:1.2
|
||
heart-beat:0,0
|
||
host:dev.xuqinmin.com
|
||
Authorization:Bearer {token}
|
||
|
||
\x00
|
||
```
|
||
|
||
> 当前服务端不强制心跳，客户端可依赖 WebSocket 原生 `onclose`/`onerror` 检测断线。
|
||
|
||
---
|
||
|
||
## 消息格式（STOMP）
|
||
|
||
### CONNECT 帧
|
||
|
||
客户端建立 WebSocket 连接后，发送 STOMP CONNECT：
|
||
|
||
```
|
||
CONNECT
|
||
accept-version:1.2
|
||
heart-beat:0,0
|
||
host:dev.xuqinmin.com
|
||
Authorization:Bearer {token}
|
||
|
||
\x00
|
||
```
|
||
|
||
### CONNECTED 帧
|
||
|
||
服务端鉴权通过后返回：
|
||
|
||
```
|
||
CONNECTED
|
||
version:1.2
|
||
|
||
\x00
|
||
```
|
||
|
||
### SUBSCRIBE 帧
|
||
|
||
订阅个人消息队列（自动执行）：
|
||
|
||
```
|
||
SUBSCRIBE
|
||
id:sub-1
|
||
destination:/user/queue/messages
|
||
|
||
\x00
|
||
```
|
||
|
||
订阅群消息：
|
||
|
||
```
|
||
SUBSCRIBE
|
||
id:sub-2
|
||
destination:/topic/group/{groupId}
|
||
|
||
\x00
|
||
```
|
||
|
||
### SEND 帧 — 发送消息
|
||
|
||
```
|
||
SEND
|
||
destination:/app/chat.send
|
||
content-type:application/json
|
||
|
||
{"appId":"ak_demo_chat","messageId":"...","toId":"user_002","chatType":"SINGLE","msgType":"TEXT","content":"Hello"}
|
||
\x00
|
||
```
|
||
|
||
### SEND 帧 — 撤回消息
|
||
|
||
```
|
||
SEND
|
||
destination:/app/chat.revoke
|
||
content-type:application/json
|
||
|
||
{"appId":"ak_demo_chat","messageId":"..."}
|
||
\x00
|
||
```
|
||
|
||
### SEND 帧 — 同步离线消息
|
||
|
||
```
|
||
SEND
|
||
destination:/app/chat.sync
|
||
content-type:application/json
|
||
|
||
{"appId":"ak_demo_chat"}
|
||
\x00
|
||
```
|
||
|
||
### MESSAGE 帧 — 接收消息
|
||
|
||
```
|
||
MESSAGE
|
||
destination:/user/queue/messages
|
||
message-id:...
|
||
|
||
{"id":"...","fromId":"user_002","toId":"user_001","chatType":"SINGLE","msgType":"TEXT","content":"Hello","status":"SENT","createdAt":1715000000000}
|
||
\x00
|
||
```
|
||
|
||
### ERROR 帧
|
||
|
||
```
|
||
ERROR
|
||
message:Unauthorized
|
||
|
||
Unauthorized
|
||
\x00
|
||
```
|
||
|
||
---
|
||
|
||
## 订阅路径
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| `/user/queue/messages` | 个人消息队列（登录后自动订阅）|
|
||
| `/topic/group/{groupId}` | 群消息频道 |
|
||
|
||
---
|
||
|
||
## 服务端配置
|
||
|
||
基于 Spring WebSocket + STOMP：
|
||
|
||
```java
|
||
@Configuration
|
||
@EnableWebSocketMessageBroker
|
||
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
|
||
@Override
|
||
public void configureMessageBroker(MessageBrokerRegistry registry) {
|
||
registry.enableSimpleBroker("/topic", "/queue");
|
||
registry.setApplicationDestinationPrefixes("/app");
|
||
registry.setUserDestinationPrefix("/user");
|
||
}
|
||
|
||
@Override
|
||
public void registerStompEndpoints(StompEndpointRegistry registry) {
|
||
registry.addEndpoint("/ws/im")
|
||
.setAllowedOriginPatterns("*")
|
||
.withSockJS();
|
||
registry.addEndpoint("/ws/im")
|
||
.setAllowedOriginPatterns("*");
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 自定义客户端接入
|
||
|
||
如果业务方不使用官方 SDK，可按以下流程自建客户端：
|
||
|
||
1. 通过 `wss://host/ws/im?token=xxx` 建立 WebSocket
|
||
2. 发送 STOMP CONNECT 帧（携带 `Authorization: Bearer {token}`）
|
||
3. 收到 CONNECTED 后，订阅 `/user/queue/messages`
|
||
4. 发送消息时构造 STOMP SEND 帧，`destination: /app/chat.send`
|
||
5. 收到服务端 MESSAGE 帧后解析 JSON body
|
||
|
||
[→ Server API 文档 →](./api)
|
