290 lines
6.9 KiB
Markdown
290 lines
6.9 KiB
Markdown
|
# 结伴客后端API文档
|
|||
|
|
|
|||
|
|
## 1. 认证相关接口
|
|||
|
|
|
|||
|
|
### 用户注册
|
|||
|
|
|
|||
|
|
**请求方法**: POST
|
|||
|
|
**请求路径**: `/api/v1/auth/register`
|
|||
|
|
**请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"username": "string", // 用户名（必需）
|
|||
|
|
"password": "string", // 密码（必需，至少6位）
|
|||
|
|
"nickname": "string", // 昵称（可选）
|
|||
|
|
"email": "string", // 邮箱（可选）
|
|||
|
|
"phone": "string" // 手机号（可选）
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
**响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {
|
|||
|
|
"user": { // 用户信息（不含敏感信息）
|
|||
|
|
"id": 1,
|
|||
|
|
"username": "testuser",
|
|||
|
|
"nickname": "测试用户",
|
|||
|
|
"email": "test@jiebanke.com",
|
|||
|
|
"phone": "13800000000",
|
|||
|
|
// 其他用户字段...
|
|||
|
|
},
|
|||
|
|
"token": "string"
|
|||
|
|
},
|
|||
|
|
"message": "注册成功"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
**错误响应**:
|
|||
|
|
- 400: 用户名已存在 / 邮箱已存在 / 手机号已存在 / 密码长度不能少于6位
|
|||
|
|
- 500: 服务器内部错误
|
|||
|
|
|
|||
|
|
### 用户登录
|
|||
|
|
|
|||
|
|
**请求方法**: POST
|
|||
|
|
**请求路径**: `/api/v1/auth/login`
|
|||
|
|
**请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"username": "string", // 用户名/邮箱/手机号（必需）
|
|||
|
|
"password": "string" // 密码（必需）
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
**响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {
|
|||
|
|
"user": { // 用户信息（不含敏感信息）
|
|||
|
|
"id": 1,
|
|||
|
|
"username": "testuser",
|
|||
|
|
"nickname": "测试用户",
|
|||
|
|
"email": "test@jiebanke.com",
|
|||
|
|
"phone": "13800000000",
|
|||
|
|
// 其他用户字段...
|
|||
|
|
},
|
|||
|
|
"token": "string"
|
|||
|
|
},
|
|||
|
|
"message": "登录成功"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
**错误响应**:
|
|||
|
|
- 400: 用户名和密码不能为空
|
|||
|
|
- 401: 密码错误
|
|||
|
|
- 403: 账户已被禁用
|
|||
|
|
- 404: 用户不存在
|
|||
|
|
- 500: 服务器内部错误
|
|||
|
|
|
|||
|
|
## 2. 用户管理接口
|
|||
|
|
|
|||
|
|
### 获取当前用户信息
|
|||
|
|
|
|||
|
|
**请求方法**: GET
|
|||
|
|
**请求路径**: `/api/v1/users/profile`
|
|||
|
|
**请求头**: `Authorization: Bearer {token}`
|
|||
|
|
**响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {
|
|||
|
|
"user": { // 用户信息（不含敏感信息）
|
|||
|
|
"id": 1,
|
|||
|
|
"username": "testuser",
|
|||
|
|
"nickname": "测试用户",
|
|||
|
|
"email": "test@jiebanke.com",
|
|||
|
|
"phone": "13800000000",
|
|||
|
|
// 其他用户字段...
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
**错误响应**:
|
|||
|
|
- 401: 未提供认证token / 无效的认证token / token已过期 / 用户不存在
|
|||
|
|
- 403: 账户已被禁用
|
|||
|
|
- 500: 服务器内部错误
|
|||
|
|
|
|||
|
|
### 更新用户个人信息
|
|||
|
|
|
|||
|
|
**请求方法**: PUT
|
|||
|
|
**请求路径**: `/api/v1/users/profile`
|
|||
|
|
**请求头**: `Authorization: Bearer {token}`
|
|||
|
|
**请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"nickname": "string", // 昵称（可选）
|
|||
|
|
"avatar": "string", // 头像URL（可选）
|
|||
|
|
"gender": "string", // 性别（可选，可选值：male, female, other）
|
|||
|
|
"birthday": "string", // 生日（可选，格式：YYYY-MM-DD）
|
|||
|
|
"phone": "string", // 手机号（可选）
|
|||
|
|
"email": "string" // 邮箱（可选）
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
**响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {
|
|||
|
|
"user": { // 更新后的用户信息（不含敏感信息）
|
|||
|
|
"id": 1,
|
|||
|
|
"username": "testuser",
|
|||
|
|
"nickname": "新昵称",
|
|||
|
|
"email": "new@email.com",
|
|||
|
|
"phone": "13900000000",
|
|||
|
|
// 其他用户字段...
|
|||
|
|
},
|
|||
|
|
"message": "个人信息更新成功"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
**错误响应**:
|
|||
|
|
- 400: 没有有效的更新字段 / 邮箱已被其他用户使用 / 手机号已被其他用户使用
|
|||
|
|
- 401: 未提供认证token / 无效的认证token / token已过期 / 用户不存在
|
|||
|
|
- 403: 账户已被禁用
|
|||
|
|
- 500: 更新用户信息失败 / 服务器内部错误
|
|||
|
|
|
|||
|
|
## 3. 管理员接口
|
|||
|
|
|
|||
|
|
### 搜索用户
|
|||
|
|
|
|||
|
|
**请求方法**: GET
|
|||
|
|
**请求路径**: `/api/v1/admin/users/search`
|
|||
|
|
**请求头**: `Authorization: Bearer {token}`
|
|||
|
|
**请求参数**:
|
|||
|
|
- keyword: 搜索关键词（可选，模糊匹配用户名、昵称、邮箱、手机号）
|
|||
|
|
- userType: 用户类型（可选）
|
|||
|
|
- page: 当前页码（可选，默认：1）
|
|||
|
|
- pageSize: 每页记录数（可选，默认：10）
|
|||
|
|
|
|||
|
|
**响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {
|
|||
|
|
"users": [
|
|||
|
|
{
|
|||
|
|
"id": 1,
|
|||
|
|
"username": "testuser",
|
|||
|
|
"user_type": "farmer",
|
|||
|
|
"real_name": "测试用户",
|
|||
|
|
"avatar_url": "",
|
|||
|
|
"email": "test@jiebanke.com",
|
|||
|
|
"phone": "13800000000",
|
|||
|
|
"status": "active",
|
|||
|
|
"created_at": "2024-01-01T12:00:00Z",
|
|||
|
|
"updated_at": "2024-01-01T12:00:00Z"
|
|||
|
|
}
|
|||
|
|
// 更多用户...
|
|||
|
|
],
|
|||
|
|
"total": 1,
|
|||
|
|
"page": 1,
|
|||
|
|
"pageSize": 10,
|
|||
|
|
"pages": 1
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
**错误响应**:
|
|||
|
|
- 401: 未提供认证token / 无效的认证token / token已过期 / 管理员不存在
|
|||
|
|
- 403: 管理员账号已被禁用 / 需要管理员权限 / 权限不足
|
|||
|
|
- 500: 服务器内部错误
|
|||
|
|
|
|||
|
|
### 批量更新用户状态
|
|||
|
|
|
|||
|
|
**请求方法**: POST
|
|||
|
|
**请求路径**: `/api/v1/admin/users/batch-status`
|
|||
|
|
**请求头**: `Authorization: Bearer {token}`
|
|||
|
|
**请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"userIds": [1, 2, 3], // 用户ID列表（必需）
|
|||
|
|
"status": "active" // 状态（必需，可选值：active, inactive）
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
**响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"success": true,
|
|||
|
|
"data": {
|
|||
|
|
"message": "成功更新 3 个用户状态",
|
|||
|
|
"affectedRows": 3
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
**错误响应**:
|
|||
|
|
- 400: 请选择要操作的用户 / 无效的状态值
|
|||
|
|
- 401: 未提供认证token / 无效的认证token / token已过期 / 管理员不存在
|
|||
|
|
- 403: 管理员账号已被禁用 / 需要管理员权限 / 权限不足
|
|||
|
|
- 500: 服务器内部错误
|
|||
|
|
|
|||
|
|
## 4. 系统接口
|
|||
|
|
|
|||
|
|
### 健康检查
|
|||
|
|
|
|||
|
|
**请求方法**: GET
|
|||
|
|
**请求路径**: `/health`
|
|||
|
|
**响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"status": "OK",
|
|||
|
|
"timestamp": "2024-01-01T12:00:00Z",
|
|||
|
|
"uptime": 1234.56,
|
|||
|
|
"environment": "production"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 系统统计
|
|||
|
|
|
|||
|
|
**请求方法**: GET
|
|||
|
|
**请求路径**: `/system-stats`
|
|||
|
|
**响应**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"status": "OK",
|
|||
|
|
"timestamp": "2024-01-01T12:00:00Z",
|
|||
|
|
"environment": "production",
|
|||
|
|
"nodeVersion": "v18.16.0",
|
|||
|
|
"memoryUsage": {
|
|||
|
|
"rss": 123456789,
|
|||
|
|
"heapTotal": 12345678,
|
|||
|
|
"heapUsed": 1234567,
|
|||
|
|
"external": 123456
|
|||
|
|
},
|
|||
|
|
"uptime": 1234.56,
|
|||
|
|
"cpuCount": 8,
|
|||
|
|
"platform": "linux",
|
|||
|
|
"architecture": "x64"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 5. 错误码说明
|
|||
|
|
|
|||
|
|
| 错误码 | 描述 | HTTP状态码 |
|
|||
|
|
|-------|------|-----------|
|
|||
|
|
| 400 | 请求参数错误 | 400 |
|
|||
|
|
| 401 | 未授权（无效token、token过期等） | 401 |
|
|||
|
|
| 403 | 权限不足或账户被禁用 | 403 |
|
|||
|
|
| 404 | 资源不存在 | 404 |
|
|||
|
|
| 429 | 请求过于频繁 | 429 |
|
|||
|
|
| 500 | 服务器内部错误 | 500 |
|
|||
|
|
| 503 | 服务不可用（如数据库连接失败） | 503 |
|
|||
|
|
|
|||
|
|
## 6. 认证机制
|
|||
|
|
|
|||
|
|
系统使用JWT（JSON Web Token）进行认证，所有需要认证的接口都需要在请求头中包含`Authorization: Bearer {token}`。
|
|||
|
|
|
|||
|
|
### Token有效期
|
|||
|
|
- 默认有效期为7天
|
|||
|
|
- 可通过环境变量`JWT_EXPIRE`自定义
|
|||
|
|
|
|||
|
|
### Token安全
|
|||
|
|
- 生产环境请确保设置安全的`JWT_SECRET`环境变量
|
|||
|
|
- 避免在客户端存储敏感信息
|
|||
|
|
|
|||
|
|
## 7. 接口限制
|
|||
|
|
|
|||
|
|
- 接口请求频率限制：生产环境15分钟内最多100次请求，开发环境15分钟内最多1000次请求
|
|||
|
|
- 请求体大小限制：10kb
|
|||
|
|
- 支持的请求内容类型：application/json
|
|||
|
|
|
|||
|
|
## 8. Swagger文档
|
|||
|
|
|
|||
|
|
在开发环境或设置`ENABLE_SWAGGER=true`环境变量时，可通过以下地址访问Swagger文档：
|
|||
|
|
- https://webapi.jiebanke.com/api-docs
|