281 lines
5.9 KiB
Plaintext
281 lines
5.9 KiB
Plaintext
|
视频观看模块接口文档
|
|||
|
|
=================
|
|||
|
|
|
|||
|
|
基础信息
|
|||
|
|
-------
|
|||
|
|
- 基础路径: /api/v1/videos
|
|||
|
|
- 请求方式: REST
|
|||
|
|
- 数据格式: JSON
|
|||
|
|
- 认证方式: Bearer Token
|
|||
|
|
|
|||
|
|
数据结构
|
|||
|
|
-------
|
|||
|
|
|
|||
|
|
Video 视频对象:
|
|||
|
|
{
|
|||
|
|
id: number, // 视频ID
|
|||
|
|
title: string, // 视频标题
|
|||
|
|
description: string, // 视频描述
|
|||
|
|
url: string, // 视频URL
|
|||
|
|
thumbnail: string, // 缩略图URL
|
|||
|
|
duration: string, // 视频时长
|
|||
|
|
category: string, // 视频分类
|
|||
|
|
views: number, // 观看次数
|
|||
|
|
likes: number, // 点赞数
|
|||
|
|
comments: number, // 评论数
|
|||
|
|
tags: string[], // 标签
|
|||
|
|
uploadTime: string, // 上传时间
|
|||
|
|
status: string // 视频状态(active/disabled)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
API 接口
|
|||
|
|
-------
|
|||
|
|
|
|||
|
|
1. 获取视频列表
|
|||
|
|
GET /api/v1/videos
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|||
|
|
| category | string | 否 | 视频分类 |
|
|||
|
|
| page | number | 否 | 页码，默认1 |
|
|||
|
|
| size | number | 否 | 每页数量，默认10 |
|
|||
|
|
| sort | string | 否 | 排序字段(uploadTime/views/likes) |
|
|||
|
|
| order | string | 否 | 排序方式(asc/desc) |
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"total": 100,
|
|||
|
|
"pages": 10,
|
|||
|
|
"current": 1,
|
|||
|
|
"records": [
|
|||
|
|
{
|
|||
|
|
"id": 1,
|
|||
|
|
"title": "每日健康操",
|
|||
|
|
"description": "适合老年人的健康运动视频",
|
|||
|
|
"url": "http://example.com/video1.mp4",
|
|||
|
|
"thumbnail": "http://example.com/thumb1.jpg",
|
|||
|
|
"duration": "10:00",
|
|||
|
|
"category": "health",
|
|||
|
|
"views": 1234,
|
|||
|
|
"likes": 256,
|
|||
|
|
"comments": 45,
|
|||
|
|
"tags": ["健康", "运动", "教学"],
|
|||
|
|
"uploadTime": "2024-03-20 10:00:00",
|
|||
|
|
"status": "active"
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
2. 获取视频详情
|
|||
|
|
GET /api/v1/videos/{id}
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"id": 1,
|
|||
|
|
"title": "每日健康操",
|
|||
|
|
"description": "适合老年人的健康运动视频",
|
|||
|
|
"url": "http://example.com/video1.mp4",
|
|||
|
|
"thumbnail": "http://example.com/thumb1.jpg",
|
|||
|
|
"duration": "10:00",
|
|||
|
|
"category": "health",
|
|||
|
|
"views": 1234,
|
|||
|
|
"likes": 256,
|
|||
|
|
"comments": 45,
|
|||
|
|
"tags": ["健康", "运动", "教学"],
|
|||
|
|
"uploadTime": "2024-03-20 10:00:00",
|
|||
|
|
"status": "active"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
3. 更新观看次数
|
|||
|
|
POST /api/v1/videos/{id}/view
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"views": 1235
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
4. 点赞视频
|
|||
|
|
POST /api/v1/videos/{id}/like
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"likes": 257
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
5. 获取推荐视频
|
|||
|
|
GET /api/v1/videos/recommended
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|||
|
|
| currentId | number | 否 | 当前视频ID |
|
|||
|
|
| limit | number | 否 | 返回数量，默认3 |
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": [
|
|||
|
|
{
|
|||
|
|
"id": 2,
|
|||
|
|
"title": "太极拳教学",
|
|||
|
|
"description": "专业老师讲解太极拳基本动作",
|
|||
|
|
"url": "http://example.com/video2.mp4",
|
|||
|
|
"thumbnail": "http://example.com/thumb2.jpg",
|
|||
|
|
"duration": "15:00",
|
|||
|
|
"category": "health",
|
|||
|
|
"views": 890,
|
|||
|
|
"likes": 156,
|
|||
|
|
"comments": 23,
|
|||
|
|
"tags": ["太极拳", "运动", "教学"],
|
|||
|
|
"uploadTime": "2024-03-19 15:00:00",
|
|||
|
|
"status": "active"
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
6. 获取热门视频
|
|||
|
|
GET /api/v1/videos/hot
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|||
|
|
| limit | number | 否 | 返回数量，默认5 |
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": [
|
|||
|
|
{
|
|||
|
|
"id": 3,
|
|||
|
|
"title": "广场舞教学",
|
|||
|
|
"description": "广场舞基础动作教学",
|
|||
|
|
"url": "http://example.com/video3.mp4",
|
|||
|
|
"thumbnail": "http://example.com/thumb3.jpg",
|
|||
|
|
"duration": "20:00",
|
|||
|
|
"category": "entertainment",
|
|||
|
|
"views": 2345,
|
|||
|
|
"likes": 456,
|
|||
|
|
"comments": 78,
|
|||
|
|
"tags": ["广场舞", "运动", "教学"],
|
|||
|
|
"uploadTime": "2024-03-18 14:00:00",
|
|||
|
|
"status": "active"
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
7. 获取视频分类
|
|||
|
|
GET /api/v1/videos/categories
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": [
|
|||
|
|
{
|
|||
|
|
"value": "health",
|
|||
|
|
"label": "健康讲座",
|
|||
|
|
"count": 25
|
|||
|
|
},
|
|||
|
|
{
|
|||
|
|
"value": "entertainment",
|
|||
|
|
"label": "娱乐节目",
|
|||
|
|
"count": 18
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
8. 添加视频评论
|
|||
|
|
POST /api/v1/videos/{id}/comments
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
{
|
|||
|
|
"content": "视频很有帮助",
|
|||
|
|
"parentId": null // 回复其他评论时设置
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"id": 1,
|
|||
|
|
"content": "视频很有帮助",
|
|||
|
|
"userId": 10001,
|
|||
|
|
"userName": "张三",
|
|||
|
|
"createTime": "2024-03-20 15:30:00",
|
|||
|
|
"parentId": null,
|
|||
|
|
"likes": 0
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
9. 获取视频评论列表
|
|||
|
|
GET /api/v1/videos/{id}/comments
|
|||
|
|
|
|||
|
|
请求参数：
|
|||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|||
|
|
| page | number | 否 | 页码，默认1 |
|
|||
|
|
| size | number | 否 | 每页数量，默认10 |
|
|||
|
|
|
|||
|
|
响应示例：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": {
|
|||
|
|
"total": 45,
|
|||
|
|
"pages": 5,
|
|||
|
|
"current": 1,
|
|||
|
|
"records": [
|
|||
|
|
{
|
|||
|
|
"id": 1,
|
|||
|
|
"content": "视频很有帮助",
|
|||
|
|
"userId": 10001,
|
|||
|
|
"userName": "张三",
|
|||
|
|
"createTime": "2024-03-20 15:30:00",
|
|||
|
|
"parentId": null,
|
|||
|
|
"likes": 5,
|
|||
|
|
"replies": []
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
错误码说明
|
|||
|
|
--------
|
|||
|
|
| 错误码 | 说明 |
|
|||
|
|
| 200 | 成功 |
|
|||
|
|
| 400 | 请求参数错误 |
|
|||
|
|
| 401 | 未授权 |
|
|||
|
|
| 403 | 禁止访问 |
|
|||
|
|
| 404 | 资源不存在 |
|
|||
|
|
| 500 | 服务器内部错误 |
|
|||
|
|
|
|||
|
|
注意事项
|
|||
|
|
-------
|
|||
|
|
1. 视频文件上传需要单独处理，建议使用分片上传：
|
|||
|
|
POST /api/v1/videos/upload
|
|||
|
|
Content-Type: multipart/form-data
|
|||
|
|
|
|||
|
|
2. 视频URL需要进行加密和有效期控制，防止视频泄露。
|
|||
|
|
|
|||
|
|
3. 视频播放建议使用 HLS 或 DASH 协议，支持多码率自适应。
|
|||
|
|
|
|||
|
|
4. 缓存策略：
|
|||
|
|
- 视频元数据缓存：5分钟
|
|||
|
|
- 视频分类缓存：1小时
|
|||
|
|
- 热门视频缓存：10分钟
|