159 lines
3.5 KiB
Markdown
159 lines
3.5 KiB
Markdown
# 前端接口文档 (Frontend API Documentation)
|
||
|
||
本文档说明如何在前端项目（微信小程序和Web管理后台）中使用接口。
|
||
|
||
## 1. 微信小程序 (WeChat Mini Program)
|
||
|
||
小程序目录：`wechat-mini-program/`
|
||
|
||
### 1.1 请求工具 (Request Utility)
|
||
|
||
封装文件：`utils/request.js`
|
||
|
||
该工具自动处理了：
|
||
- Base URL 拼接
|
||
- Token 注入 (Bearer Token)
|
||
- 响应拦截与错误处理
|
||
- 响应数据解包 (Unwrapping `data` field)
|
||
|
||
### 1.2 使用方法 (Usage)
|
||
|
||
在页面或组件中引入 `request` 方法：
|
||
|
||
```javascript
|
||
const { request } = require('../../utils/request')
|
||
// 或者在某些地方通过 app 获取 (如果挂载了)
|
||
// const app = getApp()
|
||
```
|
||
|
||
**示例代码：**
|
||
|
||
```javascript
|
||
// GET 请求
|
||
request({
|
||
url: '/projects/',
|
||
method: 'GET',
|
||
data: { page: 1, page_size: 10 }
|
||
}).then(res => {
|
||
console.log('项目列表:', res.results)
|
||
}).catch(err => {
|
||
console.error('获取失败:', err)
|
||
})
|
||
|
||
// POST 请求
|
||
request({
|
||
url: '/student-projects/',
|
||
method: 'POST',
|
||
data: {
|
||
project: 1,
|
||
status: 'enrolled'
|
||
}
|
||
}).then(res => {
|
||
wx.showToast({ title: '报名成功' })
|
||
})
|
||
```
|
||
|
||
### 1.3 常用接口封装
|
||
|
||
虽然可以直接使用 `request`，但建议在 `api/` 目录下（如果存在）或各页面 JS 中进行简单封装。
|
||
|
||
目前主要直接在 `pages/` 对应的 `.js` 文件中调用。例如 `pages/index/index.js` 调用 `/banners/` 和 `/projects/`。
|
||
|
||
---
|
||
|
||
## 2. Web 管理后台 (Admin Client)
|
||
|
||
Web 端目录：`admin/client/`
|
||
技术栈：Vue.js + Element UI
|
||
|
||
### 2.1 接口目录结构
|
||
|
||
所有 API 请求定义在 `src/api/` 目录下，按模块划分：
|
||
|
||
- `src/api/crm.js`: 核心业务接口（项目、学员、教师等）
|
||
- `src/api/system/user.js`: 系统用户接口
|
||
- `src/api/login.js`: 登录相关接口
|
||
|
||
### 2.2 定义接口 (Defining APIs)
|
||
|
||
以 `src/api/crm.js` 为例：
|
||
|
||
```javascript
|
||
import request from '@/utils/request'
|
||
|
||
// 获取教师列表
|
||
export function getTeachers(query) {
|
||
return request({
|
||
url: '/teachers/',
|
||
method: 'get',
|
||
params: query
|
||
})
|
||
}
|
||
|
||
// 创建教师
|
||
export function createTeacher(data) {
|
||
return request({
|
||
url: '/teachers/',
|
||
method: 'post',
|
||
data
|
||
})
|
||
}
|
||
```
|
||
|
||
### 2.3 在组件中使用 (Usage in Components)
|
||
|
||
在 Vue 组件中引入并调用：
|
||
|
||
```vue
|
||
<script>
|
||
import { getTeachers, createTeacher } from '@/api/crm'
|
||
|
||
export default {
|
||
data() {
|
||
return {
|
||
list: [],
|
||
query: { page: 1, limit: 20 }
|
||
}
|
||
},
|
||
created() {
|
||
this.fetchData()
|
||
},
|
||
methods: {
|
||
fetchData() {
|
||
getTeachers(this.query).then(response => {
|
||
this.list = response.data.results
|
||
// 注意：根据后端响应拦截器的配置，response 可能已经是 data 部分，
|
||
// 或者需要访问 response.data。请参考 src/utils/request.js
|
||
})
|
||
},
|
||
handleAdd() {
|
||
createTeacher(this.form).then(() => {
|
||
this.$message.success('创建成功')
|
||
this.fetchData()
|
||
})
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 2.4 请求拦截器 (Interceptors)
|
||
|
||
位置：`src/utils/request.js`
|
||
|
||
- **Request Interceptor**: 自动添加 `Authorization: Bearer <token>`
|
||
- **Response Interceptor**:
|
||
- 统一处理非 200 状态码
|
||
- 统一处理业务错误码
|
||
- 登录过期自动登出
|
||
|
||
## 3. 注意事项 (Notes)
|
||
|
||
1. **Base URL 配置**:
|
||
- 小程序：`wechat-mini-program/config/env.js` (或 `app.js`)
|
||
- Web 后台：`.env.development` 和 `.env.production` 中的 `VUE_APP_BASE_API`
|
||
|
||
2. **分页 (Pagination)**:
|
||
- 默认参数：`page` (页码), `limit` 或 `size` (每页数量)
|
||
- 响应格式：`{ count: Total, results: [Array] }`
|