647 lines
14 KiB
Go
647 lines
14 KiB
Go
# nl-video-api 在线影院后端API接口文档
|
||
|
||
## 1. 接口概述
|
||
|
||
### 1.1 基本信息
|
||
- **项目名称**: nl-video-api 在线影院后端系统
|
||
- **版本**: v1.0.0
|
||
- **基础URL**: `http://localhost:8000/api/v1`
|
||
- **认证方式**: JWT Token
|
||
- **数据格式**: JSON
|
||
|
||
### 1.2 通用响应格式
|
||
```json
|
||
{
|
||
"code": 0, // 状态码，0表示成功，非0表示失败
|
||
"message": "success", // 响应消息
|
||
"data": {} // 响应数据，可能为对象、数组或null
|
||
}
|
||
```
|
||
|
||
### 1.3 通用错误码
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 0 | 成功 |
|
||
| 1001 | 参数错误 |
|
||
| 1002 | 业务逻辑错误 |
|
||
| 1003 | 认证失败 |
|
||
| 1004 | 权限不足 |
|
||
| 1005 | 资源不存在 |
|
||
| 1006 | 资源已存在 |
|
||
| 1007 | 服务器内部错误 |
|
||
|
||
### 1.4 认证说明
|
||
- 除了登录接口外，所有接口都需要在请求头中携带JWT Token
|
||
- Header格式: `Authorization: Bearer {token}`
|
||
|
||
## 2. 认证模块
|
||
|
||
### 2.1 管理员登录
|
||
**接口地址**: `POST /auth/admin/login`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"username": "admin", // 用户名，必填
|
||
"password": "123456" // 密码，必填
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "登录成功",
|
||
"data": {
|
||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"admin": {
|
||
"id": 1,
|
||
"username": "admin",
|
||
"nickname": "超级管理员",
|
||
"email": "admin@example.com",
|
||
"status": 1,
|
||
"last_login_time": "2024-01-01 12:00:00"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 管理员注册
|
||
**接口地址**: `POST /auth/admin/register`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"username": "newadmin", // 用户名，必填，2-20位
|
||
"password": "123456", // 密码，必填，6-20位
|
||
"nickname": "新管理员", // 昵称，必填，2-20位
|
||
"email": "admin@example.com" // 邮箱，必填
|
||
}
|
||
```
|
||
|
||
### 2.3 获取当前用户信息
|
||
**接口地址**: `GET /auth/admin/info`
|
||
|
||
**请求头**: `Authorization: Bearer {token}`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "admin",
|
||
"nickname": "超级管理员",
|
||
"email": "admin@example.com",
|
||
"status": 1,
|
||
"permissions": ["user:list", "movie:create", "role:assign"]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3. 影片管理模块
|
||
|
||
### 3.1 获取影片列表
|
||
**接口地址**: `GET /movies`
|
||
|
||
**请求参数**:
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| page | int | 否 | 页码，默认1 |
|
||
| page_size | int | 否 | 每页数量，默认20 |
|
||
| title | string | 否 | 影片标题模糊搜索 |
|
||
| category_id | int | 否 | 分类ID |
|
||
| type | int | 否 | 影片类型：1电影，2电视剧 |
|
||
| status | int | 否 | 状态：0禁用，1启用 |
|
||
| year | int | 否 | 年份 |
|
||
| country | string | 否 | 国家/地区 |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"title": "复仇者联盟",
|
||
"type": 1,
|
||
"category_id": 1,
|
||
"category_name": "动作片",
|
||
"cover": "https://example.com/cover.jpg",
|
||
"year": 2012,
|
||
"country": "美国",
|
||
"director": "乔斯·韦登",
|
||
"actors": "小罗伯特·唐尼,克里斯·埃文斯",
|
||
"rating": 8.5,
|
||
"duration": 143,
|
||
"status": 1,
|
||
"created_at": "2024-01-01 12:00:00"
|
||
}
|
||
],
|
||
"total": 100,
|
||
"page": 1,
|
||
"page_size": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 创建影片
|
||
**接口地址**: `POST /admin/movies`
|
||
|
||
**请求头**: `Authorization: Bearer {token}`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"title": "新影片", // 影片标题，必填
|
||
"type": 1, // 影片类型：1电影，2电视剧，必填
|
||
"category_id": 1, // 分类ID，必填
|
||
"cover": "cover.jpg", // 封面图片，可选
|
||
"year": 2024, // 年份，必填
|
||
"country": "中国", // 国家/地区，必填
|
||
"director": "导演名", // 导演，可选
|
||
"actors": "演员1,演员2", // 演员，可选
|
||
"description": "影片描述", // 描述，可选
|
||
"duration": 120, // 时长（分钟），电影必填
|
||
"total_episodes": 24, // 总集数，电视剧必填
|
||
"status": 1 // 状态：0禁用，1启用
|
||
}
|
||
```
|
||
|
||
### 3.3 更新影片
|
||
**接口地址**: `PUT /admin/movies/{id}`
|
||
|
||
**请求参数**: 同创建影片，所有字段可选
|
||
|
||
### 3.4 删除影片
|
||
**接口地址**: `DELETE /admin/movies/{id}`
|
||
|
||
### 3.5 获取影片详情
|
||
**接口地址**: `GET /movies/{id}`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"id": 1,
|
||
"title": "复仇者联盟",
|
||
"type": 1,
|
||
"category_id": 1,
|
||
"category_name": "动作片",
|
||
"cover": "https://example.com/cover.jpg",
|
||
"year": 2012,
|
||
"country": "美国",
|
||
"director": "乔斯·韦登",
|
||
"actors": "小罗伯特·唐尼,克里斯·埃文斯",
|
||
"description": "超级英雄集结拯救世界",
|
||
"rating": 8.5,
|
||
"duration": 143,
|
||
"view_count": 10000,
|
||
"like_count": 500,
|
||
"status": 1,
|
||
"episodes": [ // 如果是电视剧，包含剧集信息
|
||
{
|
||
"id": 1,
|
||
"episode_number": 1,
|
||
"title": "第1集",
|
||
"duration": 45,
|
||
"video_url": "https://example.com/video1.mp4"
|
||
}
|
||
],
|
||
"created_at": "2024-01-01 12:00:00",
|
||
"updated_at": "2024-01-01 12:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 4. 用户管理模块
|
||
|
||
### 4.1 获取用户列表
|
||
**接口地址**: `GET /admin/users`
|
||
|
||
**请求头**: `Authorization: Bearer {token}`
|
||
|
||
**请求参数**:
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| page | int | 否 | 页码，默认1 |
|
||
| page_size | int | 否 | 每页数量，默认20 |
|
||
| username | string | 否 | 用户名模糊搜索 |
|
||
| phone | string | 否 | 手机号模糊搜索 |
|
||
| email | string | 否 | 邮箱模糊搜索 |
|
||
| status | int | 否 | 状态：0禁用，1启用 |
|
||
| vip_level | int | 否 | VIP等级：0-10 |
|
||
| gender | int | 否 | 性别：0未知，1男，2女 |
|
||
| start_time | string | 否 | 注册开始时间 |
|
||
| end_time | string | 否 | 注册结束时间 |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"username": "user001",
|
||
"phone": "13800138000",
|
||
"email": "user@example.com",
|
||
"nickname": "普通用户",
|
||
"avatar": "https://example.com/avatar.jpg",
|
||
"gender": 1,
|
||
"vip_level": 2,
|
||
"vip_expire_time": "2024-12-31 23:59:59",
|
||
"balance": 100.50,
|
||
"points": 1000,
|
||
"status": 1,
|
||
"last_login_time": "2024-01-01 12:00:00",
|
||
"last_login_ip": "192.168.1.1",
|
||
"created_at": "2024-01-01 10:00:00"
|
||
}
|
||
],
|
||
"total": 500,
|
||
"page": 1,
|
||
"page_size": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.2 创建用户
|
||
**接口地址**: `POST /admin/users`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"username": "newuser", // 用户名，必填，2-20位，唯一
|
||
"phone": "13800138001", // 手机号，必填，11位，唯一
|
||
"email": "user@example.com", // 邮箱，必填，唯一
|
||
"password": "123456", // 密码，必填，6-20位
|
||
"nickname": "新用户", // 昵称，必填，2-20位
|
||
"gender": 1, // 性别：0未知，1男，2女
|
||
"vip_level": 0, // VIP等级，0-10
|
||
"status": 1 // 状态：0禁用，1启用
|
||
}
|
||
```
|
||
|
||
### 4.3 更新用户信息
|
||
**接口地址**: `PUT /admin/users/{id}`
|
||
|
||
**请求参数**: 同创建用户，除username外所有字段可选
|
||
|
||
### 4.4 删除用户
|
||
**接口地址**: `DELETE /admin/users/{id}`
|
||
|
||
### 4.5 升级用户VIP
|
||
**接口地址**: `POST /admin/users/{id}/vip`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"vip_level": 3, // VIP等级，1-10
|
||
"days": 30 // 有效天数
|
||
}
|
||
```
|
||
|
||
### 4.6 更新用户余额
|
||
**接口地址**: `PUT /admin/users/{id}/balance`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"amount": 100.50, // 金额，正数为增加，负数为减少
|
||
"type": 1, // 类型：1充值，2消费，3退款，4奖励
|
||
"remark": "管理员充值" // 备注
|
||
}
|
||
```
|
||
|
||
### 4.7 更新用户积分
|
||
**接口地址**: `PUT /admin/users/{id}/points`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"points": 500, // 积分，正数为增加，负数为减少
|
||
"type": 1, // 类型：1签到，2消费，3奖励，4兑换
|
||
"remark": "活动奖励" // 备注
|
||
}
|
||
```
|
||
|
||
## 5. 权限管理模块
|
||
|
||
### 5.1 获取角色列表
|
||
**接口地址**: `GET /admin/roles`
|
||
|
||
**请求头**: `Authorization: Bearer {token}`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"name": "超级管理员",
|
||
"code": "super_admin",
|
||
"level": 1,
|
||
"description": "系统最高权限",
|
||
"sort": 1,
|
||
"status": 1,
|
||
"is_system": 1,
|
||
"created_at": "2024-01-01 10:00:00"
|
||
}
|
||
],
|
||
"total": 5,
|
||
"page": 1,
|
||
"page_size": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.2 创建角色
|
||
**接口地址**: `POST /admin/roles`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"name": "内容管理员", // 角色名称，必填，2-50位
|
||
"code": "content_admin", // 角色编码，必填，2-50位，唯一
|
||
"level": 3, // 角色等级，1-10
|
||
"description": "负责内容管理", // 角色描述
|
||
"sort": 10, // 排序
|
||
"status": 1 // 状态：0禁用，1启用
|
||
}
|
||
```
|
||
|
||
### 5.3 为角色分配权限
|
||
**接口地址**: `POST /admin/roles/{id}/permissions`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"permission_ids": [1, 2, 3, 4, 5] // 权限ID数组
|
||
}
|
||
```
|
||
|
||
### 5.4 获取权限列表
|
||
**接口地址**: `GET /admin/permissions`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"name": "用户管理",
|
||
"code": "user:manage",
|
||
"type": 1,
|
||
"parent_id": 0,
|
||
"path": "/admin/users",
|
||
"method": "GET",
|
||
"icon": "user",
|
||
"sort": 1,
|
||
"status": 1,
|
||
"children": [
|
||
{
|
||
"id": 2,
|
||
"name": "用户列表",
|
||
"code": "user:list",
|
||
"type": 2,
|
||
"parent_id": 1,
|
||
"path": "/admin/users",
|
||
"method": "GET"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 6. 分类管理模块
|
||
|
||
### 6.1 获取分类列表
|
||
**接口地址**: `GET /categories`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"name": "动作片",
|
||
"parent_id": 0,
|
||
"sort": 1,
|
||
"status": 1,
|
||
"children": [
|
||
{
|
||
"id": 2,
|
||
"name": "科幻动作",
|
||
"parent_id": 1,
|
||
"sort": 1,
|
||
"status": 1
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.2 创建分类
|
||
**接口地址**: `POST /admin/categories`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"name": "新分类", // 分类名称，必填
|
||
"parent_id": 0, // 父分类ID，0为顶级分类
|
||
"sort": 1, // 排序
|
||
"status": 1 // 状态：0禁用，1启用
|
||
}
|
||
```
|
||
|
||
## 7. 剧集管理模块
|
||
|
||
### 7.1 获取剧集列表
|
||
**接口地址**: `GET /admin/movies/{movie_id}/episodes`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"movie_id": 1,
|
||
"episode_number": 1,
|
||
"title": "第1集",
|
||
"duration": 45,
|
||
"video_url": "https://example.com/video1.mp4",
|
||
"status": 1,
|
||
"created_at": "2024-01-01 12:00:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.2 创建剧集
|
||
**接口地址**: `POST /admin/movies/{movie_id}/episodes`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"episode_number": 1, // 集数，必填
|
||
"title": "第1集", // 标题，必填
|
||
"duration": 45, // 时长（分钟），必填
|
||
"video_url": "video1.mp4", // 视频文件，必填
|
||
"status": 1 // 状态：0禁用，1启用
|
||
}
|
||
```
|
||
|
||
## 8. 统计分析模块
|
||
|
||
### 8.1 获取系统统计
|
||
**接口地址**: `GET /admin/stats`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"users": {
|
||
"total": 10000,
|
||
"today_new": 50,
|
||
"active": 5000,
|
||
"vip": 1000
|
||
},
|
||
"movies": {
|
||
"total": 500,
|
||
"today_new": 5,
|
||
"hot": 100
|
||
},
|
||
"views": {
|
||
"total": 1000000,
|
||
"today": 10000
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 9. 文件上传模块
|
||
|
||
### 9.1 上传文件
|
||
**接口地址**: `POST /upload`
|
||
|
||
**请求方式**: `multipart/form-data`
|
||
|
||
**请求参数**:
|
||
- `file`: 文件，必填
|
||
- `type`: 文件类型，可选（image/video/document）
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "上传成功",
|
||
"data": {
|
||
"url": "https://example.com/uploads/2024/01/01/file.jpg",
|
||
"filename": "file.jpg",
|
||
"size": 1024000,
|
||
"type": "image/jpeg"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 10. 搜索模块
|
||
|
||
### 10.1 全局搜索
|
||
**接口地址**: `GET /search`
|
||
|
||
**请求参数**:
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| keyword | string | 是 | 搜索关键词 |
|
||
| type | string | 否 | 搜索类型：movie/user/all |
|
||
| page | int | 否 | 页码，默认1 |
|
||
| page_size | int | 否 | 每页数量，默认20 |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "搜索成功",
|
||
"data": {
|
||
"movies": [
|
||
{
|
||
"id": 1,
|
||
"title": "复仇者联盟",
|
||
"cover": "https://example.com/cover.jpg",
|
||
"rating": 8.5,
|
||
"year": 2012
|
||
}
|
||
],
|
||
"total": 10,
|
||
"page": 1,
|
||
"page_size": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
## 11. 接口测试说明
|
||
|
||
### 11.1 测试环境
|
||
- 服务器地址: `http://localhost:8000`
|
||
- 测试工具: Postman、ApiPost、VS Code REST Client
|
||
|
||
### 11.2 测试流程
|
||
1. 启动服务器: `go run main.go`
|
||
2. 初始化数据库: `go run main.go init-db`
|
||
3. 管理员登录获取Token
|
||
4. 使用Token测试其他接口
|
||
|
||
### 11.3 测试用例
|
||
项目提供了完整的HTTP测试文件：
|
||
- `test_movie_api.http` - 影片管理接口测试
|
||
- `test_user_api.http` - 用户管理接口测试
|
||
- `test_permission_api.http` - 权限管理接口测试
|
||
|
||
## 12. 错误处理
|
||
|
||
### 12.1 常见错误
|
||
| 错误码 | HTTP状态码 | 错误信息 | 解决方案 |
|
||
|--------|------------|----------|----------|
|
||
| 1001 | 400 | 参数错误 | 检查请求参数格式和必填项 |
|
||
| 1003 | 401 | 认证失败 | 检查Token是否有效 |
|
||
| 1004 | 403 | 权限不足 | 检查用户权限 |
|
||
| 1005 | 404 | 资源不存在 | 检查资源ID是否正确 |
|
||
| 1006 | 409 | 资源已存在 | 检查唯一性约束 |
|
||
|
||
### 12.2 调试建议
|
||
1. 检查请求URL和方法是否正确
|
||
2. 确认请求头包含正确的Token
|
||
3. 验证请求参数格式和类型
|
||
4. 查看服务器日志获取详细错误信息
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0.0
|
||
**最后更新**: 2024-01-01
|
||
**维护者**: nl-video-api开发团队 |