349 lines
7.4 KiB
Markdown
349 lines
7.4 KiB
Markdown
# API 接口文档
|
||
|
||
这是在线学习平台的前端API接口封装，提供了完整的类型定义和请求方法。
|
||
|
||
## 📁 文件结构
|
||
|
||
```
|
||
src/api/
|
||
├── index.ts # 统一导出文件
|
||
├── types.ts # TypeScript 类型定义
|
||
├── request.ts # HTTP 请求封装
|
||
├── utils.ts # 工具函数
|
||
├── modules/ # API 模块
|
||
│ ├── auth.ts # 认证相关API
|
||
│ ├── course.ts # 课程相关API
|
||
│ ├── comment.ts # 评论相关API
|
||
│ ├── favorite.ts # 收藏相关API
|
||
│ ├── order.ts # 订单相关API
|
||
│ ├── upload.ts # 文件上传API
|
||
│ └── statistics.ts # 统计相关API
|
||
├── examples/ # 使用示例
|
||
│ └── usage.ts # API使用示例
|
||
└── README.md # 文档说明
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 环境配置
|
||
|
||
复制 `.env.example` 为 `.env.local` 并配置API地址：
|
||
|
||
```bash
|
||
cp .env.example .env.local
|
||
```
|
||
|
||
```env
|
||
# API 配置
|
||
VITE_API_BASE_URL=http://localhost:3000/api
|
||
VITE_API_TIMEOUT=10000
|
||
```
|
||
|
||
### 2. 基础使用
|
||
|
||
```typescript
|
||
import { AuthApi, CourseApi } from '@/api'
|
||
|
||
// 用户登录
|
||
const login = async () => {
|
||
try {
|
||
const response = await AuthApi.login({
|
||
email: 'user@example.com',
|
||
password: 'password123'
|
||
})
|
||
|
||
if (response.code === 200) {
|
||
console.log('登录成功:', response.data)
|
||
}
|
||
} catch (error) {
|
||
console.error('登录失败:', error)
|
||
}
|
||
}
|
||
|
||
// 获取课程列表
|
||
const getCourses = async () => {
|
||
try {
|
||
const response = await CourseApi.getCourses({
|
||
page: 1,
|
||
pageSize: 20,
|
||
category: '前端开发'
|
||
})
|
||
|
||
if (response.code === 200) {
|
||
console.log('课程列表:', response.data)
|
||
}
|
||
} catch (error) {
|
||
console.error('获取课程失败:', error)
|
||
}
|
||
}
|
||
```
|
||
|
||
## 📚 API 模块说明
|
||
|
||
### 认证模块 (AuthApi)
|
||
|
||
提供用户认证相关的所有接口：
|
||
|
||
- `login()` - 用户登录
|
||
- `register()` - 用户注册
|
||
- `logout()` - 用户登出
|
||
- `getCurrentUser()` - 获取当前用户信息
|
||
- `updateProfile()` - 更新用户资料
|
||
- `changePassword()` - 修改密码
|
||
- `uploadAvatar()` - 上传头像
|
||
|
||
### 课程模块 (CourseApi)
|
||
|
||
提供课程相关的所有接口：
|
||
|
||
- `getCourses()` - 获取课程列表
|
||
- `searchCourses()` - 搜索课程
|
||
- `getCourseById()` - 获取课程详情
|
||
- `enrollCourse()` - 报名课程
|
||
- `getLearningProgress()` - 获取学习进度
|
||
- `getCourseChapters()` - 获取课程章节
|
||
- `getCourseLessons()` - 获取课程课时
|
||
|
||
### 评论模块 (CommentApi)
|
||
|
||
提供评论相关的所有接口：
|
||
|
||
- `getCourseComments()` - 获取课程评论
|
||
- `addCourseComment()` - 添加课程评论
|
||
- `likeComment()` - 点赞评论
|
||
- `updateComment()` - 更新评论
|
||
- `deleteComment()` - 删除评论
|
||
|
||
### 收藏模块 (FavoriteApi)
|
||
|
||
提供收藏相关的所有接口：
|
||
|
||
- `addFavorite()` - 添加收藏
|
||
- `removeFavorite()` - 取消收藏
|
||
- `getMyFavorites()` - 获取收藏列表
|
||
- `checkFavorite()` - 检查收藏状态
|
||
|
||
### 订单模块 (OrderApi)
|
||
|
||
提供订单相关的所有接口：
|
||
|
||
- `createOrder()` - 创建订单
|
||
- `getOrders()` - 获取订单列表
|
||
- `getOrderById()` - 获取订单详情
|
||
- `cancelOrder()` - 取消订单
|
||
- `confirmPayment()` - 确认支付
|
||
|
||
### 上传模块 (UploadApi)
|
||
|
||
提供文件上传相关的所有接口：
|
||
|
||
- `uploadFile()` - 上传单个文件
|
||
- `uploadAvatar()` - 上传头像
|
||
- `uploadCourseVideo()` - 上传课程视频
|
||
- `uploadMultipleFiles()` - 批量上传文件
|
||
|
||
### 统计模块 (StatisticsApi)
|
||
|
||
提供统计相关的所有接口：
|
||
|
||
- `getPlatformStats()` - 获取平台统计
|
||
- `getUserLearningStats()` - 获取用户学习统计
|
||
- `getCourseStats()` - 获取课程统计
|
||
|
||
## 🔧 工具函数
|
||
|
||
### 请求工具
|
||
|
||
```typescript
|
||
import { ApiRequest } from '@/api'
|
||
|
||
// GET 请求
|
||
const data = await ApiRequest.get('/endpoint', { param: 'value' })
|
||
|
||
// POST 请求
|
||
const result = await ApiRequest.post('/endpoint', { data: 'value' })
|
||
|
||
// 文件上传
|
||
const uploadResult = await ApiRequest.upload('/upload', file, (progress) => {
|
||
console.log('上传进度:', progress + '%')
|
||
})
|
||
```
|
||
|
||
### 工具函数
|
||
|
||
```typescript
|
||
import {
|
||
buildQueryString,
|
||
formatFileSize,
|
||
formatDuration,
|
||
isValidEmail,
|
||
storage
|
||
} from '@/api/utils'
|
||
|
||
// 构建查询字符串
|
||
const query = buildQueryString({ page: 1, size: 20 })
|
||
|
||
// 格式化文件大小
|
||
const size = formatFileSize(1024000) // "1000 KB"
|
||
|
||
// 格式化时长
|
||
const duration = formatDuration(3661) // "1小时1分1秒"
|
||
|
||
// 验证邮箱
|
||
const valid = isValidEmail('user@example.com') // true
|
||
|
||
// 本地存储
|
||
storage.set('user', { id: 1, name: 'John' })
|
||
const user = storage.get('user')
|
||
```
|
||
|
||
## 🎯 类型定义
|
||
|
||
所有API都有完整的TypeScript类型定义：
|
||
|
||
```typescript
|
||
import type {
|
||
User,
|
||
Course,
|
||
Comment,
|
||
Order,
|
||
ApiResponse,
|
||
PaginationResponse
|
||
} from '@/api'
|
||
|
||
// 用户类型
|
||
const user: User = {
|
||
id: 1,
|
||
username: 'john',
|
||
email: 'john@example.com',
|
||
role: 'student'
|
||
}
|
||
|
||
// API响应类型
|
||
const response: ApiResponse<User> = {
|
||
code: 200,
|
||
message: '成功',
|
||
data: user
|
||
}
|
||
|
||
// 分页响应类型
|
||
const pageResponse: ApiResponse<PaginationResponse<Course>> = {
|
||
code: 200,
|
||
message: '成功',
|
||
data: {
|
||
list: [],
|
||
total: 100,
|
||
page: 1,
|
||
pageSize: 20,
|
||
totalPages: 5
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🛠️ 错误处理
|
||
|
||
### 全局错误处理
|
||
|
||
请求拦截器会自动处理常见错误：
|
||
|
||
- 401: 自动跳转登录页
|
||
- 403: 显示权限不足提示
|
||
- 500: 显示服务器错误提示
|
||
- 网络错误: 显示网络连接提示
|
||
|
||
### 自定义错误处理
|
||
|
||
```typescript
|
||
import { getErrorMessage } from '@/api/utils'
|
||
|
||
try {
|
||
const response = await AuthApi.login(credentials)
|
||
} catch (error) {
|
||
const message = getErrorMessage(error)
|
||
console.error('登录失败:', message)
|
||
// 显示错误提示
|
||
}
|
||
```
|
||
|
||
## 📝 最佳实践
|
||
|
||
### 1. 使用TypeScript类型
|
||
|
||
```typescript
|
||
import type { Course, ApiResponse } from '@/api'
|
||
|
||
const handleCourseData = (response: ApiResponse<Course[]>) => {
|
||
if (response.code === 200) {
|
||
response.data.forEach(course => {
|
||
// TypeScript 会提供完整的类型提示
|
||
console.log(course.title, course.instructor.name)
|
||
})
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 错误边界处理
|
||
|
||
```typescript
|
||
const fetchData = async () => {
|
||
try {
|
||
const response = await CourseApi.getCourses()
|
||
return response.data
|
||
} catch (error) {
|
||
// 记录错误日志
|
||
console.error('API Error:', error)
|
||
// 返回默认值或重新抛出错误
|
||
throw error
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 加载状态管理
|
||
|
||
```typescript
|
||
const loading = ref(false)
|
||
|
||
const loadCourses = async () => {
|
||
loading.value = true
|
||
try {
|
||
const response = await CourseApi.getCourses()
|
||
// 处理数据
|
||
} catch (error) {
|
||
// 处理错误
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 分页数据处理
|
||
|
||
```typescript
|
||
import { formatPaginationData } from '@/api/utils'
|
||
|
||
const loadCourses = async (page: number = 1) => {
|
||
try {
|
||
const response = await CourseApi.getCourses({ page, pageSize: 20 })
|
||
const pagination = formatPaginationData(response)
|
||
|
||
console.log('课程列表:', pagination.items)
|
||
console.log('分页信息:', {
|
||
current: pagination.currentPage,
|
||
total: pagination.totalPages,
|
||
hasNext: pagination.hasNext
|
||
})
|
||
} catch (error) {
|
||
console.error('加载失败:', error)
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🔄 更新日志
|
||
|
||
### v1.0.0
|
||
- 初始版本
|
||
- 完整的API接口封装
|
||
- TypeScript类型定义
|
||
- 错误处理机制
|
||
- 工具函数库
|