338 lines
5.6 KiB
Markdown
338 lines
5.6 KiB
Markdown
|
## HTTP API
|
|||
|
|
|
|||
|
|
### 1. 用户注册
|
|||
|
|
- **URL**: `/api/register`
|
|||
|
|
- **方法**: `POST`
|
|||
|
|
- **请求头**: `Content-Type: application/json`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"username": "string",
|
|||
|
|
"password": "string",
|
|||
|
|
"avatar": "string" // 可选，默认为'default_avatar.png'
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **响应**:
|
|||
|
|
- 成功:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "register_1",
|
|||
|
|
"error": false,
|
|||
|
|
"message": "User registered successfully"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 用户名已存在:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "register_0",
|
|||
|
|
"success": false,
|
|||
|
|
"message": "Username already exists"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 用户名格式错误（返回状态码400）:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "register_-2",
|
|||
|
|
"success": false,
|
|||
|
|
"message": "Invalid username. Must be 2-20 characters, start with a letter or symbol, and contain only letters, numbers, or symbols: _!@#$%^&+-~?"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 头像格式错误（仅允许.png或.jpg）:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "register_0",
|
|||
|
|
"success": False,
|
|||
|
|
"message": "Invalid avatar format. Only .png or .jpg allowed"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 其他错误（如数据库错误）:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "register_-1",
|
|||
|
|
"error": true,
|
|||
|
|
"message": "错误详情"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 用户登录
|
|||
|
|
- **URL**: `/api/login`
|
|||
|
|
- **方法**: `POST`
|
|||
|
|
- **请求头**: `Content-Type: application/json`
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"username": "string",
|
|||
|
|
"password": "string"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **响应**:
|
|||
|
|
- 成功:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "login_1",
|
|||
|
|
"status": "success",
|
|||
|
|
"token": "string", // 令牌，用于后续请求
|
|||
|
|
"avatar": "string" // 用户头像的URL
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 账号已登录（返回状态码409）:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "login",
|
|||
|
|
"status": "error_0",
|
|||
|
|
"message": "Account already logged in"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 凭证错误:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "login_0",
|
|||
|
|
"status": "error",
|
|||
|
|
"message": "Invalid credentials"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 发送聊天消息
|
|||
|
|
- **URL**: `/api/chat`
|
|||
|
|
- **方法**: `POST`
|
|||
|
|
- **请求头**: `Content-Type: application/json`
|
|||
|
|
- `Authorization: <token>` // 登录时获取的令牌
|
|||
|
|
- **请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"message": "string"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **响应**:
|
|||
|
|
- 成功:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "chat",
|
|||
|
|
"status": "success"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 令牌无效或缺失（返回状态码401）:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "chat",
|
|||
|
|
"status": "error"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4. 获取头像
|
|||
|
|
- **URL**: `/avatar/<username>/<filename>`
|
|||
|
|
- **方法**: `GET`
|
|||
|
|
- **响应**:
|
|||
|
|
- 返回用户头像文件（如果存在），否则返回默认头像。
|
|||
|
|
|
|||
|
|
|
|||
|
|
## Socket API
|
|||
|
|
Socket服务器运行在`8889`端口。客户端连接后，可以发送JSON格式的消息。每个消息必须包含`type`字段，表示操作类型。
|
|||
|
|
|
|||
|
|
### 消息格式
|
|||
|
|
所有消息均为JSON格式，编码为UTF-8字符串发送。
|
|||
|
|
|
|||
|
|
### 1. 注册
|
|||
|
|
- **请求**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "register",
|
|||
|
|
"username": "string",
|
|||
|
|
"password": "string",
|
|||
|
|
"avatar": "string" // 可选
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **响应**:
|
|||
|
|
- 成功:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "register_1",
|
|||
|
|
"error": false,
|
|||
|
|
"message": "User registered successfully"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 用户名已存在:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "register_0",
|
|||
|
|
"success": false,
|
|||
|
|
"message": "Username already exists"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 用户名格式错误:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "register_-2",
|
|||
|
|
"success": false,
|
|||
|
|
"message": "Invalid username format"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 头像格式错误:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "register_-3",
|
|||
|
|
"success": false,
|
|||
|
|
"message": "Invalid avatar format. Only .png or .jpg allowed"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 登录
|
|||
|
|
- **请求**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "login",
|
|||
|
|
"username": "string",
|
|||
|
|
"password": "string"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **响应**:
|
|||
|
|
- 成功:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "login",
|
|||
|
|
"status": "success",
|
|||
|
|
"message": "Login successful",
|
|||
|
|
"token": "string", // 用于后续操作的令牌
|
|||
|
|
"username": "string", // 登录的用户名
|
|||
|
|
"avatar": "string" // 头像URL
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 账号已登录:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "login",
|
|||
|
|
"status": "error_-1",
|
|||
|
|
"message": "Account already logged in"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 凭证错误:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "login",
|
|||
|
|
"status": "error_0",
|
|||
|
|
"message": "Invalid credentials"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 发送聊天消息
|
|||
|
|
- **请求**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "chat",
|
|||
|
|
"token": "string", // 登录时获取的令牌
|
|||
|
|
"message": "string" // 聊天内容
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **响应**:
|
|||
|
|
- 成功:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "chat",
|
|||
|
|
"status": "success"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 令牌无效:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "chat",
|
|||
|
|
"status": "error_It",
|
|||
|
|
"message": "Invalid token"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 未登录:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "chat",
|
|||
|
|
"status": "error_Nli",
|
|||
|
|
"message": "Not logged in"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4. 心跳检测
|
|||
|
|
- **请求**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "heartbeat",
|
|||
|
|
"token": "string"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **响应**:
|
|||
|
|
- 成功:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "heartbeat",
|
|||
|
|
"status": "success"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 失败:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "heartbeat",
|
|||
|
|
"status": "error"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 错误码说明
|
|||
|
|
|
|||
|
|
### 注册相关
|
|||
|
|
- `register_1`: 注册成功
|
|||
|
|
- `register_0`: 用户名已存在
|
|||
|
|
- `register_-1`: 数据库错误
|
|||
|
|
- `register_-2`: 用户名格式错误
|
|||
|
|
- `register_-3`: 头像格式错误（仅Socket）
|
|||
|
|
|
|||
|
|
### 登录相关
|
|||
|
|
- `login_1`: 登录成功（HTTP）
|
|||
|
|
- `login_0`: 凭证错误（HTTP）或登录失败（Socket中为`error_0`）
|
|||
|
|
- `error_-1`（Socket）: 账号已登录
|
|||
|
|
|
|||
|
|
### 聊天相关
|
|||
|
|
- `error_Mt`: 令牌缺失（Socket）
|
|||
|
|
- `error_It`: 令牌无效（Socket）
|
|||
|
|
- `error_Nli`: 未登录（Socket）
|
|||
|
|
|
|||
|
|
## 用户名校验规则
|
|||
|
|
- 长度：2-20个字符
|
|||
|
|
- 只能包含字母、数字以及特定符号：`_!@#$%^&+-~?`
|
|||
|
|
- 不能以数字开头
|
|||
|
|
|
|||
|
|
## 头像规则
|
|||
|
|
- 头像文件名必须以`.png`或`.jpg`结尾。
|
|||
|
|
- 每个用户有专属的头像目录，位于`avatar/<username>`下。
|
|||
|
|
- 默认头像为`avatar/default/default_avatar.png`。
|
|||
|
|
|
|||
|
|
## 连接管理
|
|||
|
|
- 每个用户只能有一个活跃连接。如果尝试登录时已有活跃连接，则拒绝登录（HTTP返回409，Socket返回错误）。
|
|||
|
|
- 服务器会定期（5分钟）检查不活跃的连接并清理。
|
|||
|
|
|
|||
|
|
- 客户端应每5分钟发送一次心跳包以保持连接活跃。
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
- 令牌有效期为1小时，每次使用会刷新有效期。
|
|||
|
|
|
|||
|
|
- 头像的获取通过HTTP GET请求，路径为`/avatar/<username>/<filename>`。
|
|||
|
|
|
|||
|
|
请根据实际情况调整使用。
|