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分钟 |