From 79c991ee642519923e0d9d1435e78b568fcd4bb0 Mon Sep 17 00:00:00 2001 From: Qyir <13521889462@163.com> Date: Fri, 17 Oct 2025 18:23:42 +0800 Subject: [PATCH] =?UTF-8?q?API=E6=96=87=E6=A1=A3=E6=8E=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- handlers/Rankings/docs/API接口文档.md | 462 ++++++++++++++++++++++++++ 1 file changed, 462 insertions(+) create mode 100644 handlers/Rankings/docs/API接口文档.md diff --git a/handlers/Rankings/docs/API接口文档.md b/handlers/Rankings/docs/API接口文档.md new file mode 100644 index 0000000..7511946 --- /dev/null +++ b/handlers/Rankings/docs/API接口文档.md @@ -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**维护者**：系统自动生成 \ No newline at end of file