code/IM
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
main
IM/docs/接口文档（REST API） — 聊天系统.md
nanxun 848e18e057 Init
2025-10-13 17:07:12 +08:00

8.0 KiB
Raw Permalink Blame History

接口文档（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