API文档接口
This commit is contained in:
parent
c37c9106fa
commit
79c991ee64
462
handlers/Rankings/docs/API接口文档.md
Normal file
462
handlers/Rankings/docs/API接口文档.md
Normal file
@ -0,0 +1,462 @@
|
||||
# 抖音播放量数据API接口文档
|
||||
|
||||
## 概述
|
||||
|
||||
本API服务提供抖音播放量数据的查询、搜索、统计等功能，专为小程序优化设计。
|
||||
|
||||
**基础信息**
|
||||
- 服务地址：`http://localhost:5000`
|
||||
- 数据源：MongoDB数据库
|
||||
- 数据更新：每晚24:00自动更新
|
||||
- 响应格式：JSON
|
||||
|
||||
## 通用响应格式
|
||||
|
||||
所有API接口都遵循以下响应格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {},
|
||||
"message": "操作成功",
|
||||
"update_time": "2025-10-17 15:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**
|
||||
- `success`: 请求是否成功
|
||||
- `data`: 返回的数据内容
|
||||
- `message`: 操作结果描述
|
||||
- `update_time`: 数据更新时间
|
||||
|
||||
## 数据模型
|
||||
|
||||
### 合集数据项
|
||||
```json
|
||||
{
|
||||
"_id": "674f1234567890abcdef",
|
||||
"batch_time": "2025-10-17 15:30:00",
|
||||
"mix_name": "合集名称",
|
||||
"video_url": "https://www.douyin.com/video/xxx",
|
||||
"playcount": "1.2亿",
|
||||
"play_vv": 120000000,
|
||||
"request_id": "request_xxx",
|
||||
"rank": 1,
|
||||
"cover_image_url": "https://p3.douyinpic.com/xxx",
|
||||
"cover_backup_urls": ["url1", "url2"]
|
||||
}
|
||||
```
|
||||
|
||||
### 分页信息
|
||||
```json
|
||||
{
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 100,
|
||||
"pages": 5,
|
||||
"has_next": true,
|
||||
"has_prev": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API接口列表
|
||||
|
||||
### 1. 首页信息
|
||||
|
||||
**接口地址**
|
||||
```
|
||||
GET /
|
||||
```
|
||||
|
||||
**功能描述**
|
||||
获取API服务的基本信息和所有可用接口列表
|
||||
|
||||
**请求参数**
|
||||
无
|
||||
|
||||
**响应示例**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"name": "抖音播放量数据API服务",
|
||||
"version": "2.0",
|
||||
"description": "主程序服务 - 整合小程序API功能",
|
||||
"endpoints": {
|
||||
"/api/videos": "获取视频列表 (支持分页和排序)",
|
||||
"/api/top": "获取热门视频榜单",
|
||||
"/api/search": "搜索视频",
|
||||
"/api/detail": "获取视频详情",
|
||||
"/api/stats": "获取统计信息",
|
||||
"/api/health": "健康检查"
|
||||
},
|
||||
"features": [
|
||||
"分页支持",
|
||||
"多种排序方式",
|
||||
"搜索功能",
|
||||
"详情查看",
|
||||
"统计分析",
|
||||
"小程序优化"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 获取视频列表
|
||||
|
||||
**接口地址**
|
||||
```
|
||||
GET /api/videos
|
||||
```
|
||||
|
||||
**功能描述**
|
||||
获取分页的视频合集列表，支持多种排序方式
|
||||
|
||||
**请求参数**
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|--------|------|------|--------|------|
|
||||
| page | int | 否 | 1 | 页码 |
|
||||
| limit | int | 否 | 20 | 每页数量 |
|
||||
| sort | string | 否 | playcount | 排序方式：playcount(播放量) / growth(增长量) |
|
||||
| start_date | string | 否 | 昨天 | 增长计算开始日期(格式: YYYY-MM-DD) |
|
||||
| end_date | string | 否 | 今天 | 增长计算结束日期(格式: YYYY-MM-DD) |
|
||||
|
||||
**使用示例**
|
||||
```
|
||||
# 按播放量排序
|
||||
GET /api/videos?page=1&limit=20&sort=playcount
|
||||
|
||||
# 按增长量排序（默认昨天到今天的增长）
|
||||
GET /api/videos?page=1&limit=20&sort=growth
|
||||
|
||||
# 按自定义日期范围的增长排序
|
||||
GET /api/videos?page=1&limit=20&sort=growth&start_date=2025-10-16&end_date=2025-10-17
|
||||
```
|
||||
|
||||
**响应示例**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"_id": "674f1234567890abcdef",
|
||||
"batch_time": "2025-10-17 15:30:00",
|
||||
"mix_name": "热门合集1",
|
||||
"video_url": "https://www.douyin.com/video/xxx",
|
||||
"playcount": "1.2亿",
|
||||
"play_vv": 120000000,
|
||||
"request_id": "request_xxx",
|
||||
"rank": 1,
|
||||
"cover_image_url": "https://p3.douyinpic.com/xxx",
|
||||
"cover_backup_urls": ["url1", "url2"]
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 100,
|
||||
"pages": 5,
|
||||
"has_next": true,
|
||||
"has_prev": false
|
||||
},
|
||||
"sort_by": "playcount",
|
||||
"update_time": "2025-10-17 15:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 获取热门榜单
|
||||
|
||||
**接口地址**
|
||||
```
|
||||
GET /api/top
|
||||
```
|
||||
|
||||
**功能描述**
|
||||
获取热门视频榜单（按播放量排序）
|
||||
|
||||
**请求参数**
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|--------|------|------|--------|------|
|
||||
| limit | int | 否 | 10 | 返回数量 |
|
||||
|
||||
**使用示例**
|
||||
```
|
||||
GET /api/top?limit=10
|
||||
```
|
||||
|
||||
**响应示例**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"_id": "674f1234567890abcdef",
|
||||
"batch_time": "2025-10-17 15:30:00",
|
||||
"mix_name": "热门合集1",
|
||||
"video_url": "https://www.douyin.com/video/xxx",
|
||||
"playcount": "1.2亿",
|
||||
"play_vv": 120000000,
|
||||
"request_id": "request_xxx",
|
||||
"rank": 1,
|
||||
"cover_image_url": "https://p3.douyinpic.com/xxx",
|
||||
"cover_backup_urls": ["url1", "url2"]
|
||||
}
|
||||
],
|
||||
"total": 10,
|
||||
"update_time": "2025-10-17 15:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 搜索视频
|
||||
|
||||
**接口地址**
|
||||
```
|
||||
GET /api/search
|
||||
```
|
||||
|
||||
**功能描述**
|
||||
根据关键词搜索视频合集
|
||||
|
||||
**请求参数**
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|--------|------|------|--------|------|
|
||||
| q | string | 是 | - | 搜索关键词 |
|
||||
| page | int | 否 | 1 | 页码 |
|
||||
| limit | int | 否 | 10 | 每页数量 |
|
||||
|
||||
**使用示例**
|
||||
```
|
||||
GET /api/search?q=关键词&page=1&limit=10
|
||||
```
|
||||
|
||||
**响应示例**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"_id": "674f1234567890abcdef",
|
||||
"batch_time": "2025-10-17 15:30:00",
|
||||
"mix_name": "包含关键词的合集",
|
||||
"video_url": "https://www.douyin.com/video/xxx",
|
||||
"playcount": "1.2亿",
|
||||
"play_vv": 120000000,
|
||||
"request_id": "request_xxx",
|
||||
"rank": 1,
|
||||
"cover_image_url": "https://p3.douyinpic.com/xxx",
|
||||
"cover_backup_urls": ["url1", "url2"]
|
||||
}
|
||||
],
|
||||
"keyword": "关键词",
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 10,
|
||||
"total": 15,
|
||||
"pages": 2,
|
||||
"has_next": true,
|
||||
"has_prev": false
|
||||
},
|
||||
"update_time": "2025-10-17 15:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 获取视频详情
|
||||
|
||||
**接口地址**
|
||||
```
|
||||
GET /api/detail
|
||||
```
|
||||
|
||||
**功能描述**
|
||||
获取指定合集的详细信息
|
||||
|
||||
**请求参数**
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|--------|------|------|--------|------|
|
||||
| id | string | 是 | - | 合集ID（支持ObjectId、合集名称、request_id） |
|
||||
|
||||
**使用示例**
|
||||
```
|
||||
GET /api/detail?id=674f1234567890abcdef
|
||||
```
|
||||
|
||||
**响应示例**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"_id": "674f1234567890abcdef",
|
||||
"batch_time": "2025-10-17 15:30:00",
|
||||
"mix_name": "合集名称",
|
||||
"video_url": "https://www.douyin.com/video/xxx",
|
||||
"playcount": "1.2亿",
|
||||
"play_vv": 120000000,
|
||||
"request_id": "request_xxx",
|
||||
"rank": 1,
|
||||
"cover_image_url": "https://p3.douyinpic.com/xxx",
|
||||
"cover_backup_urls": ["url1", "url2"]
|
||||
},
|
||||
"update_time": "2025-10-17 15:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 6. 获取统计信息
|
||||
|
||||
**接口地址**
|
||||
```
|
||||
GET /api/stats
|
||||
```
|
||||
|
||||
**功能描述**
|
||||
获取系统统计信息
|
||||
|
||||
**请求参数**
|
||||
无
|
||||
|
||||
**响应示例**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"total_mixes": 1000,
|
||||
"total_playcount": 5000000000,
|
||||
"avg_playcount": 5000000,
|
||||
"max_playcount": 200000000,
|
||||
"min_playcount": 1000,
|
||||
"categories": [
|
||||
{
|
||||
"name": "超热门",
|
||||
"min": 100000000,
|
||||
"count": 5
|
||||
},
|
||||
{
|
||||
"name": "热门",
|
||||
"min": 50000000,
|
||||
"max": 99999999,
|
||||
"count": 20
|
||||
},
|
||||
{
|
||||
"name": "中等",
|
||||
"min": 10000000,
|
||||
"max": 49999999,
|
||||
"count": 150
|
||||
},
|
||||
{
|
||||
"name": "一般",
|
||||
"min": 0,
|
||||
"max": 9999999,
|
||||
"count": 825
|
||||
}
|
||||
],
|
||||
"latest_update": "2025-10-17 15:30:00"
|
||||
},
|
||||
"update_time": "2025-10-17 15:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 7. 健康检查
|
||||
|
||||
**接口地址**
|
||||
```
|
||||
GET /api/health
|
||||
```
|
||||
|
||||
**功能描述**
|
||||
检查服务状态和数据库连接
|
||||
|
||||
**请求参数**
|
||||
无
|
||||
|
||||
**响应示例**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "服务正常",
|
||||
"data": {
|
||||
"database": "连接正常",
|
||||
"total_records": 1000,
|
||||
"timestamp": "2025-10-17 15:30:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 通用错误格式
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "错误描述",
|
||||
"update_time": "2025-10-17 15:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 常见错误
|
||||
- `数据库连接失败`：MongoDB连接异常
|
||||
- `未找到合集信息`：查询的合集不存在
|
||||
- `请提供搜索关键词`：搜索接口缺少关键词参数
|
||||
- `获取数据失败`：数据查询异常
|
||||
|
||||
## 小程序使用建议
|
||||
|
||||
### 1. 分页加载
|
||||
推荐使用分页加载，避免一次性加载过多数据：
|
||||
```javascript
|
||||
// 小程序端示例
|
||||
wx.request({
|
||||
url: 'http://localhost:5000/api/videos',
|
||||
data: {
|
||||
page: 1,
|
||||
limit: 20,
|
||||
sort: 'playcount'
|
||||
},
|
||||
success: (res) => {
|
||||
if (res.data.success) {
|
||||
this.setData({
|
||||
videos: res.data.data,
|
||||
hasNext: res.data.pagination.has_next
|
||||
})
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### 2. 搜索优化
|
||||
- 使用防抖处理搜索请求
|
||||
- 显示搜索进度和结果数量
|
||||
- 提供搜索建议
|
||||
|
||||
### 3. 图片加载
|
||||
- 优先使用 `cover_image_url`
|
||||
- 备用 `cover_backup_urls` 作为备选
|
||||
- 添加图片加载失败处理
|
||||
|
||||
### 4. 数据更新
|
||||
- 注意 `update_time` 字段，判断数据新鲜度
|
||||
- 合理使用缓存策略
|
||||
- 定期检查服务健康状态
|
||||
|
||||
## 部署说明
|
||||
|
||||
### 启动服务
|
||||
```bash
|
||||
cd C:\Users\EDY\Desktop\rank_backend
|
||||
python app.py
|
||||
```
|
||||
|
||||
### 服务信息
|
||||
- 端口：5000
|
||||
- 数据库：MongoDB (localhost:27017)
|
||||
- 数据更新：每晚24:00自动执行
|
||||
|
||||
### 注意事项
|
||||
- 确保MongoDB服务已启动
|
||||
- 确保网络连接正常
|
||||
- 小程序端需要配置合法域名（生产环境）
|
||||
|
||||
---
|
||||
|
||||
**文档版本**：v2.0
|
||||
**最后更新**：2025-10-17**维护者**：系统自动生成
|
||||
Loading…
x
Reference in New Issue
Block a user