263 lines
6.9 KiB
Markdown
263 lines
6.9 KiB
Markdown
# 即时通讯模块 REST API (IM)
|
||
|
||
> 通用规范（认证方式、响应格式、错误码）见 [README.md](../README.md)
|
||
> 消息的实时收发（发送/撤回/标记已读/正在输入）通过 WebSocket 完成，见 [websocket.md](../websocket.md)
|
||
> 本文档中的接口用于会话管理和消息历史查询等非实时操作。
|
||
> **最后更新：** 2026-03-03（Phase 2d 文件上传 API 新增）
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | /api/v1/im/conversations | 需认证 | 获取会话列表 |
|
||
| GET | /api/v1/im/messages | 需认证 | 获取历史消息（游标分页） |
|
||
| PUT | /api/v1/im/conversations/:id/pin | 需认证 | 置顶/取消置顶 |
|
||
| PUT | /api/v1/im/conversations/:id/dnd | 需认证 | 设置/取消消息免打扰 |
|
||
| DELETE | /api/v1/im/conversations/:id | 需认证 | 删除会话（软删除） |
|
||
| DELETE | /api/v1/im/conversations/:id/messages | 需认证 | 清空聊天记录（个人视图） |
|
||
| GET | /api/v1/im/messages/search | 需认证 | 全局消息搜索 |
|
||
| GET | /api/v1/im/unread | 需认证 | 获取全局未读消息总数 |
|
||
| GET | /api/v1/im/messages/:id/reads | 需认证 | 获取消息已读详情 |
|
||
| POST | /api/v1/upload/image | 需认证 | 图片上传（含缩略图生成）[Phase 2d] |
|
||
| POST | /api/v1/upload/voice | 需认证 | 语音上传（含时长校验）[Phase 2d] |
|
||
| POST | /api/v1/upload | 需认证 | 通用文件上传（最大 50MB）[Phase 2d] |
|
||
|
||
---
|
||
|
||
## 1. 获取会话列表
|
||
|
||
`GET /api/v1/im/conversations`
|
||
|
||
**权限：** 需认证
|
||
|
||
**说明：** 返回当前用户的所有会话，排序：置顶优先 → 最后消息时间降序。已软删除的会话不返回。通过 LEFT JOIN 一次获取单聊对方用户 ID，避免 N+1 查询。
|
||
|
||
**成功响应：**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"type": 1,
|
||
"peer_user_id": 2,
|
||
"peer_nickname": "李四",
|
||
"peer_avatar": "https://...",
|
||
"last_msg_content": "你好",
|
||
"last_msg_time": "2026-03-03 10:30:00",
|
||
"last_msg_sender_id": 2,
|
||
"is_pinned": false,
|
||
"unread_count": 3
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 获取历史消息
|
||
|
||
`GET /api/v1/im/messages`
|
||
|
||
**权限：** 需认证，且为该会话成员
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| conversation_id | int | 是 | - | 会话 ID |
|
||
| before_id | int | 否 | 0 | 游标：查询 ID 小于此值的消息，0=最新 |
|
||
| limit | int | 否 | 30 | 每次获取数量，最大 100 |
|
||
|
||
**说明：** 支持 `clear_before_msg_id` 个人视图过滤（清空聊天记录后，仅过滤当前用户视图，不影响对方）。
|
||
|
||
**成功响应：**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 99,
|
||
"conversation_id": 1,
|
||
"sender_id": 2,
|
||
"type": 1,
|
||
"content": "你好",
|
||
"status": 1,
|
||
"client_msg_id": "",
|
||
"created_at": "2026-03-03 10:29:00"
|
||
}
|
||
],
|
||
"has_more": true
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 置顶/取消置顶会话
|
||
|
||
`PUT /api/v1/im/conversations/:id/pin`
|
||
|
||
**权限：** 需认证，且为该会话成员
|
||
|
||
**请求参数：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| is_pinned | bool | 是 | true=置顶, false=取消 |
|
||
|
||
---
|
||
|
||
## 3.5 设置/取消消息免打扰
|
||
|
||
`PUT /api/v1/im/conversations/:id/dnd`
|
||
|
||
**权限：** 需认证，且为该会话成员
|
||
|
||
**请求参数：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| is_do_not_disturb | bool | 是 | true=开启免打扰, false=关闭 |
|
||
|
||
**说明：** 免打扰模式下，新消息仍计入会话 unread_count，但不递增 Redis 全局未读数，前端会话列表中以灰色数字展示未读数。
|
||
|
||
---
|
||
|
||
## 4. 删除会话
|
||
|
||
`DELETE /api/v1/im/conversations/:id`
|
||
|
||
**权限：** 需认证，且为该会话成员
|
||
|
||
**说明：** 软删除，仅影响当前用户视图，不影响对方。同时清零未读数并更新 Redis 全局未读。
|
||
|
||
---
|
||
|
||
## 5. 清空聊天记录
|
||
|
||
`DELETE /api/v1/im/conversations/:id/messages`
|
||
|
||
**权限：** 需认证，且为该会话成员
|
||
|
||
**说明：** 个人视图操作，不影响对方的消息。实现方式：记录清空时的最后消息 ID（`clear_before_msg_id`），后续查询历史消息时过滤。同时清零该会话未读数。
|
||
|
||
---
|
||
|
||
## 6. 全局消息搜索
|
||
|
||
`GET /api/v1/im/messages/search`
|
||
|
||
**权限：** 需认证
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| keyword | string | 是 | - | 搜索关键词 |
|
||
| limit | int | 否 | 50 | 返回条数上限 |
|
||
|
||
**说明：** 使用 PostgreSQL GIN 全文索引（`to_tsvector('simple', content) @@ plainto_tsquery('simple', ?)`），仅搜索用户所在会话的消息。
|
||
|
||
**成功响应：**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 99,
|
||
"conversation_id": 1,
|
||
"sender_id": 2,
|
||
"type": 1,
|
||
"content": "你好世界",
|
||
"status": 1,
|
||
"created_at": "2026-03-03 10:29:00",
|
||
"sender_nickname": "李四",
|
||
"sender_avatar": "https://..."
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 获取全局未读消息总数
|
||
|
||
`GET /api/v1/im/unread`
|
||
|
||
**权限：** 需认证
|
||
|
||
**说明：** 从 Redis STRING 读取全局未读总数，用于 TabBar badge 显示。
|
||
|
||
**成功响应：**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"total_unread": 5
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 获取消息已读详情
|
||
|
||
`GET /api/v1/im/messages/:id/reads`
|
||
|
||
**权限：** 需认证，且为该会话成员
|
||
|
||
**说明：** 返回指定消息的已读/未读用户列表。群聊场景下，已设群昵称的用户会额外返回 `group_nickname` 字段。
|
||
|
||
**成功响应：**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"read_list": [
|
||
{
|
||
"user_id": 4,
|
||
"user_nickname": "张三",
|
||
"user_avatar": "https://...",
|
||
"group_nickname": "群昵称A",
|
||
"read_at": ""
|
||
}
|
||
],
|
||
"unread_list": [
|
||
{
|
||
"user_id": 5,
|
||
"user_nickname": "李四",
|
||
"user_avatar": "https://..."
|
||
}
|
||
],
|
||
"read_count": 1,
|
||
"total_count": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| group_nickname | 群内昵称，仅群聊有效且已设置时返回（omitempty） |
|
||
| read_at | 已读时间（当前暂为空，预留字段） |
|
||
| total_count | 群成员总数（不含消息发送者本人） |
|