前端接口文档 (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 方法：

const { request } = require('../../utils/request')
// 或者在某些地方通过 app 获取 (如果挂载了)
// const app = getApp()

示例代码：

// 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 为例：

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 组件中引入并调用：

<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)

Base URL 配置:
- 小程序：wechat-mini-program/config/env.js (或 app.js)
- Web 后台：.env.development 和 .env.production 中的 VUE_APP_BASE_API
分页 (Pagination):
- 默认参数：page (页码), limit 或 size (每页数量)
- 响应格式：{ count: Total, results: [Array] }

3.5 KiB Raw Blame History Unescape Escape