268 行
4.3 KiB
Markdown
268 行
4.3 KiB
Markdown
|
# Server API 参考
|
|||
|
|
|
|||
|
|
**Base URL**：`https://sentry.xuqinmin.com`
|
|||
|
|
|
|||
|
|
所有 API 通过 Nginx 反代，无需区分内部端口。
|
|||
|
|
|
|||
|
|
## 认证
|
|||
|
|
|
|||
|
|
除 `/api/im/auth/login` 外，所有 IM 接口需在请求头携带 JWT Token：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
Authorization: Bearer <token>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Token 由 `/api/im/auth/login` 接口签发。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## IM 服务（/api/im/）
|
|||
|
|
|
|||
|
|
### 登录 · 获取 Token
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
POST /api/im/auth/login
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Query 参数**
|
|||
|
|
|
|||
|
|
| 参数 | 必填 | 说明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `appId` | 是 | 应用 ID |
|
|||
|
|
| `userId` | 是 | 用户 ID |
|
|||
|
|
| `nickname` | 是 | 昵称 |
|
|||
|
|
|
|||
|
|
**响应**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{ "token": "eyJ..." }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### WebSocket 连接
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
WSS /ws/im?token=<token>&appId=<appId>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 协议：STOMP over WebSocket
|
|||
|
|
- 单聊订阅：`/user/{userId}/queue/messages`
|
|||
|
|
- 群聊订阅：`/topic/group/{groupId}`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 发送消息
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
POST /api/im/messages
|
|||
|
|
Authorization: Bearer <token>
|
|||
|
|
Content-Type: application/json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**请求体**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"toId": "user_002",
|
|||
|
|
"chatType": "SINGLE",
|
|||
|
|
"msgType": "TEXT",
|
|||
|
|
"content": "Hello!"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`chatType`：`SINGLE` | `GROUP`
|
|||
|
|
|
|||
|
|
`msgType`：`TEXT` | `IMAGE` | `VIDEO` | `AUDIO` | `FILE` | `CUSTOM` | `LOCATION` | `NOTIFY` | `RICH_TEXT` | `CALL_AUDIO` | `CALL_VIDEO` | `FORWARD`
|
|||
|
|
|
|||
|
|
**响应**：`ImMessage` 对象
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 撤回消息
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
PUT /api/im/messages/{messageId}/revoke
|
|||
|
|
Authorization: Bearer <token>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应**：更新后的 `ImMessage`（`status: "REVOKED"`，`msgType: "REVOKED"`）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 消息历史（单聊）
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
GET /api/im/messages/history?appId=&userId=&toId=&page=0&size=50
|
|||
|
|
Authorization: Bearer <token>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应**：分页 `ImMessage` 列表
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 创建群组
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
POST /api/im/groups
|
|||
|
|
Authorization: Bearer <token>
|
|||
|
|
Content-Type: application/json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"appId": "ak_demo_chat",
|
|||
|
|
"name": "开发群",
|
|||
|
|
"memberIds": ["user_001", "user_002"]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应**：`ImGroup` 对象
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 获取群列表
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
GET /api/im/groups?appId=ak_demo_chat
|
|||
|
|
Authorization: Bearer <token>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 添加群成员
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
POST /api/im/groups/{groupId}/members
|
|||
|
|
Authorization: Bearer <token>
|
|||
|
|
Content-Type: application/json
|
|||
|
|
|
|||
|
|
{ "userId": "user_003" }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 移除群成员
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
DELETE /api/im/groups/{groupId}/members/{targetUserId}
|
|||
|
|
Authorization: Bearer <token>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 版本管理服务（/api/v1/updates/ 和 /api/v1/rn/）
|
|||
|
|
|
|||
|
|
### 检查 App 更新
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
GET /api/v1/updates/check?appId=&platform=ANDROID&versionCode=1
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"hasUpdate": true,
|
|||
|
|
"versionCode": 2,
|
|||
|
|
"versionName": "1.0.1",
|
|||
|
|
"forceUpdate": false,
|
|||
|
|
"downloadUrl": "https://cdn.example.com/app.apk",
|
|||
|
|
"appStoreUrl": null,
|
|||
|
|
"releaseNotes": "修复若干问题"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 检查 RN Bundle 热更新
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
GET /api/v1/rn/check?appId=&moduleId=home&version=1.0.0&platform=ANDROID
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**响应**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"hasUpdate": true,
|
|||
|
|
"version": "1.0.1",
|
|||
|
|
"downloadUrl": "https://cdn.example.com/bundles/home_1.0.1.bundle",
|
|||
|
|
"md5": "a1b2c3d4...",
|
|||
|
|
"size": 204800
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 下载 Bundle
|
|||
|
|
|
|||
|
|
`downloadUrl` 返回的 URL 可直接 `GET` 下载，响应体为 bundle 二进制内容。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 租户服务（/api/）
|
|||
|
|
|
|||
|
|
### 创建应用（租户管理后台调用）
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
POST /api/apps
|
|||
|
|
Authorization: Bearer <tenant_token>
|
|||
|
|
Content-Type: application/json
|
|||
|
|
|
|||
|
|
{ "name": "我的 App", "platform": "ANDROID" }
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 数据模型
|
|||
|
|
|
|||
|
|
### ImMessage
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"id": "uuid",
|
|||
|
|
"appId": "ak_demo_chat",
|
|||
|
|
"fromUserId": "user_001",
|
|||
|
|
"toId": "user_002",
|
|||
|
|
"chatType": "SINGLE",
|
|||
|
|
"msgType": "TEXT",
|
|||
|
|
"content": "Hello!",
|
|||
|
|
"status": "SENT",
|
|||
|
|
"mentionedUserIds": [],
|
|||
|
|
"createdAt": "2026-04-24T10:00:00"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### ImGroup
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"id": "group_uuid",
|
|||
|
|
"appId": "ak_demo_chat",
|
|||
|
|
"name": "开发群",
|
|||
|
|
"creatorId": "user_001",
|
|||
|
|
"memberIds": ["user_001", "user_002"],
|
|||
|
|
"adminIds": ["user_001"],
|
|||
|
|
"createdAt": "2026-04-24T10:00:00"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 错误码
|
|||
|
|
|
|||
|
|
| HTTP 状态 | code | 说明 |
|
|||
|
|
|-----------|------|------|
|
|||
|
|
| 400 | 400 | 请求参数错误 |
|
|||
|
|
| 401 | 401 | Token 无效或过期 |
|
|||
|
|
| 403 | 403 | 无权限操作（如撤回他人消息）|
|
|||
|
|
| 404 | 404 | 资源不存在 |
|
|||
|
|
| 500 | 500 | 服务器内部错误 |
|
|||
|
|
|
|||
|
|
错误响应格式：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{ "code": 403, "message": "只能撤回自己发送的消息" }
|
|||
|
|
```
|
