IM/docs/接口文档（REST API） — 聊天系统.md

接口文档（REST API） — 聊天系统

统一响应格式（JSON）

{
  "code": 0,
  "message": "请求成功",
  "data": {}
}

• code：参照响应 Code 规范（0 成功，非 0 为错误）。
• message：提示文本。
• data：返回主体。

---

通用约定

• 所有需要登录的接口必须在 Header 中带 Authorization: Bearer <token>。
• 时间戳统一使用 Unix 秒。
• 分页统一采用 page（第几页，从1开始）与 limit（每页大小）或基于时间/消息ID的 afterMessageId / beforeTimestamp。
• 幂等性：对于可能重试的写操作，请求体中带 requestId。
• Content-Type: application/json（文件上传除外）。
• 返回错误码请参考前面的响应 Code 文档。

---

目录

1. 鉴权（Auth）
2. 用户（User）
3. 好友（Friend）
4. 会话（Conversation）
5. 消息（Message）
6. 文件/上传（File）
7. 群组（Group）
8. 通知（Notification）
9. 管理后台（Admin）
10. 常见错误与限流

---

1. 鉴权（Auth）

1.1 注册

• URL: POST /api/v1/auth/register
• 请求：

{
  "username": "alice",
  "password": "password123",
  "phone": "13800000000",
  "email":"admin@admin.com",
  "nickname":"测试用户",
  "avatar": "https://cdn.example.com/avatar/1001.png",
}

• 成功响应：

{
  "code": 0,
  "message": "注册成功",
  "data": { "userId": 1001 }
}

1.2 登录（返回 Token）

• URL: POST /api/v1/auth/login
• 请求：

{
  "username": "alice",
  "password": "password123",
  "deviceId": "uuid-device-001"
}

• 成功响应：

{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "eyJ....",
    "expires_in": 3600,
    "refreshToken": "rft-xxxx"
  }
}

1.3 刷新 Token

• URL: POST /api/v1/auth/refresh
• 请求：

{ "refreshToken": "rft-xxxx", "deviceId": "uuid-device-001" }

• 响应同登录（返回新 token）。

---

2. 用户（User）

2.1 获取当前用户信息

• URL: GET /api/v1/user/me
• Header: Authorization: Bearer <token>
• 响应 data 示例：

{
  "id": 1001,
  "username": "alice",
  "nickname": "Alice",
  "avatar": "https://cdn.example.com/avatar/1001.png",
  "status": 1
}

2.2 修改用户资料

• URL: PUT /api/v1/user/profile
• 请求：

{
  "nickname": "小艾",
  "olinestatus": "0",
  "avatar": "https://..."
}

2.3 根据 id 查询用户（用于搜索/加好友）

• URL: GET /api/v1/user/{userId}
• 响应含基本公开信息（不含敏感字段）。

---

3. 好友（Friend）

3.1 发送好友申请

• URL: POST /api/v1/friend/request
• 请求：

{
  "toUserId": 1002,
  "Description": "我们在项目中认识，申请加好友",
  "requestId": "uuid-req-001"  // 幂等字段
}

• 成功返回 requestId 或新记录 id。

3.2 列出好友申请（收/发）

• URL: GET /api/v1/friend/requests?type=received|sent&page=1&limit=20

3.3 处理好友申请（同意/拒绝）

• URL: POST /api/v1/friend/request/{requestId}/handle
• 请求：

{ "action": "accept" } // accept | reject

3.4 获取好友列表

• URL: GET /api/v1/friend/list?page=1&limit=50
• 返回：好友数组（id, nickname, avatar, remark）

3.5 删除好友 / 拉黑

• URL: DELETE /api/v1/friend/{friendId}
• URL: POST /api/v1/friend/{friendId}/block

---

4. 会话（Conversation）

4.1 获取会话列表（聊天列表）

• URL: GET /api/v1/conversations?page=1&limit=50
• 返回每条会话示例：

{
  "targetId": 1002,
  "chatType": "single",
  "lastMessage": { "messageId": 50001, "contentType":"text", "content":"你好", "timestamp": 1700000000 },
  "unreadCount": 3,
  "updatedAt": 1700000000
}

4.2 删除会话（清空会话/历史）

• URL: DELETE /api/v1/conversation/{chatType}/{targetId}
• 注：chatType 为 single 或 group。删除会影响客户端显示/未读计数，历史消息视策略保留或软删除。

---

5. 消息（Message）

说明：即时消息优先通过 WebSocket 发送/接收；REST 接口用于历史消息读取、离线发送（备用）、ACK、撤回等。

5.1 发送消息（HTTP 版备用）

• URL: POST /api/v1/message/send
• 请求：

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

• 响应：

{ "code": 0, "data": { "messageId": 50001, "status": "sent" } }

• 注意：若用户在线，后端可同时通过 WebSocket 推送到接收端。

5.2 拉取历史消息（分页或基于消息ID）

• URL: GET /api/v1/messages/history?chatType=single&targetId=1002&beforeMessageId=50000&limit=50
• 返回消息数组（按时间倒序或正序，双方约定）。

5.3 同步未读/离线消息（登录/重连时）

• URL: GET /api/v1/messages/sync?since=1700000000 或 afterMessageId=xxxxx
• 返回：所有未读/未同步消息（或给定时间段内消息）。

5.4 消息已读/送达回执（HTTP）

• URL: POST /api/v1/message/ack
• 请求：

{
  "messageId": 50001,
  "status": "read", // delivered | read
  "chatType": "single",
  "from": 1002, // ack 发送者（接收方）
  "to": 1001
}

5.5 撤回消息

• URL: POST /api/v1/message/{messageId}/recall
• 请求：

{ "requestId": "uuid-recall-001" }

• 响应成功后，服务器会向相关在线端推送 MESSAGE_RECALL 事件，更新 message.status。

5.6 删除单条消息（客户端侧删除/服务端删除）

• URL: DELETE /api/v1/message/{messageId}
• 注意区分“仅自己删除”与“全局删除（撤回）”。

---

6. 文件/上传（File）

6.1 上传文件（图片/语音/文档）

• URL: POST /api/v1/file/upload
• Content-Type: multipart/form-data
• 字段：file，可选 type、attachedMessageRequestId
• 成功响应：

{
  "code": 0,
  "data": {
    "fileId": 9001,
    "fileUrl": "https://oss.example.com/xxx.jpg",
    "fileName": "xxx.jpg",
    "fileSize": 12345
  }
}

• 建议：文件先上传到对象存储（OSS/S3/MinIO），返回 URL，消息发送时引用该 URL（message.content）。

6.2 下载文件

• 直接访问 fileUrl 或通过后端代理下载（带鉴权）。

---

7. 群组（Group）

7.1 创建群

• URL: POST /api/v1/group/create
• 请求：

{
  "name": "项目群",
  "ownerId": 1001,
  "memberIds": [1002,1003],
  "maxMembers": 500,
  "needApproval": true // 加群是否需要审批
}

• 响应返回 groupId。

7.2 获取群信息

• URL: GET /api/v1/group/{groupId}

7.3 邀请入群

• URL: POST /api/v1/group/{groupId}/invite
• 请求：

{ "inviter":1001, "invitees":[1004,1005], "message":"来加入我们吧" }

• 若群需要审批，发送 group_join_request；否则直接加入并更新 group_member。

7.4 加群申请（用户申请）

• URL: POST /api/v1/group/{groupId}/join-request
• 管理员/群主处理：POST /api/v1/group/join-request/{requestId}/handle

7.5 群成员管理（踢人/设管理员/退出群）

• 踢人：POST /api/v1/group/{groupId}/kick
• 退出：POST /api/v1/group/{groupId}/leave
• 设管理员：POST /api/v1/group/{groupId}/role

---

8. 通知（Notification）

8.1 获取通知列表

• URL: GET /api/v1/notifications?page=1&limit=50
• 类型包含：好友请求、群邀请、系统公告等。

8.2 标记通知为已读

• URL: POST /api/v1/notification/{notificationId}/read

---

9. 管理后台（Admin）

仅管理员或具备权限的账号访问（需在 token 中包含角色或额外权限校验）

9.1 管理员登录（同 auth）

• URL: POST /api/v1/admin/login

9.2 查询用户列表

• URL: GET /api/v1/admin/users?page=1&limit=50&keyword=alice

9.3 禁用/启用用户

• URL: POST /api/v1/admin/user/{userId}/ban
• 请求：

{ "action": "ban", "reason": "违规传播" } // action: ban | unban

9.4 查询操作日志

• URL: GET /api/v1/admin/logs?page=1&limit=50