zyt/MINI_PROGRAM_API_INTEGRATION.md

小程序 API 集成总结

概述

已完成小程序与后端 API 的集成，使用 main.js 中定义的全局 apiUrl 方法进行统一的 API 请求管理。

核心文件

1. 全局配置 (main.js)

位置: TUICallKit-Vue3/main.js

功能:

• 定义全局 baseUrl：http://api.zzzhengyangtang.cn
• 定义全局 apiUrl 方法用于发送 HTTP 请求
• 自动处理 token 和请求头
• 自动处理登录失效（code === -1）

特点:

• 支持 Vue2 和 Vue3
• 自动显示/隐藏加载中
• 支持自定义请求头
• 15秒超时设置

2. API 服务层 (utils/api.js)

位置: TUICallKit-Vue3/utils/api.js

功能:

• 封装 request() 方法
• 提供 get() 和 post() 便捷方法
• 定义医生相关 API (doctorApi)
• 降级方案：当全局 apiUrl 不可用时，直接使用 uni.request

医生 API:

doctorApi.getDoctorList(params)      // 获取医生列表
doctorApi.getDoctorDetail(id)        // 获取医生详情
doctorApi.getDoctorRoster(id, date)  // 获取医生排班

3. 首页组件 (pages/index/index.vue)

位置: TUICallKit-Vue3/pages/index/index.vue

功能:

• 展示古典卷轴风格幻灯片
• 动态加载医生列表
• 医生卡片点击跳转到挂号页面

流程:

1. 页面加载时调用 onMounted()
2. onMounted() 调用 fetchDoctors()
3. fetchDoctors() 调用 doctorApi.getDoctorList()
4. 获取成功后更新 doctors 数据
5. 医生卡片自动渲染

后端 API 端点

医生列表

请求:

GET /api/doctor/lists?page_no=1&page_size=10

响应:

{
  "code": 1,
  "msg": "success",
  "data": {
    "lists": [
      {
        "id": 1,
        "name": "张医生",
        "account": "doctor1",
        "avatar": "http://example.com/avatar.jpg",
        "mobile": "13800138000",
        "email": "doctor@example.com",
        "specialty": "医生",
        "title": "医生",
        "rating": "4.8"
      }
    ],
    "count": 10,
    "page_no": 1,
    "page_size": 10
  }
}

医生详情

请求:

GET /api/doctor/detail?id=1

医生排班

请求:

GET /api/doctor/roster?doctor_id=1&date=2024-03-11

使用示例

在组件中使用

<script setup>
import { ref, onMounted } from 'vue'
import { doctorApi } from '../utils/api'

const doctors = ref([])

const fetchDoctors = async () => {
  try {
    const response = await doctorApi.getDoctorList({
      page_no: 1,
      page_size: 10
    })
    
    if (response.code === 1) {
      doctors.value = response.data.lists || []
    } else {
      uni.showToast({
        title: response.msg || '获取失败',
        icon: 'none'
      })
    }
  } catch (error) {
    console.error('请求失败:', error)
  }
}

onMounted(() => {
  fetchDoctors()
})
</script>

请求流程

组件调用 doctorApi.getDoctorList()
    ↓
调用 get('/api/doctor/lists', params, false)
    ↓
调用 request('/api/doctor/lists', 'GET', params, false)
    ↓
获取全局 apiUrl 方法
    ↓
调用 apiUrl({ url, method, data, header }, loading)
    ↓
main.js 中的 apiUrl 方法处理请求
    ↓
uni.request 发送 HTTP 请求
    ↓
返回响应数据

错误处理

自动处理

1. 登录失效 (code === -1)

   • 自动清除 token
   • 可选：跳转到登录页

2. 网络错误

   • 自动显示/隐藏加载中
   • 返回错误信息

手动处理

try {
  const response = await doctorApi.getDoctorList({ page_no: 1 })
  
  if (response.code === 1) {
    // 成功
    console.log(response.data)
  } else if (response.code === -1) {
    // 登录失效
    uni.redirectTo({ url: '/pages/login/login' })
  } else {
    // 其他错误
    uni.showToast({
      title: response.msg || '请求失败',
      icon: 'none'
    })
  }
} catch (error) {
  // 网络错误
  console.error('网络错误:', error)
}

配置修改

修改 API 基础 URL

编辑 TUICallKit-Vue3/main.js：

var baseUrl = 'http://your-api-domain/api'

修改超时时间

编辑 TUICallKit-Vue3/main.js 中的 uni.request：

timeout: 20000  // 改为 20 秒

修改请求头

编辑 TUICallKit-Vue3/main.js 中的 header 对象：

const header = {
  token: token,
  'content-type': 'application/x-www-form-urlencoded',
  'X-Custom-Header': 'custom-value'
}

扩展功能

添加新的 API 模块

在 TUICallKit-Vue3/utils/api.js 中添加：

export const appointmentApi = {
  getList: (params) => get('/api/appointment/lists', params, false),
  create: (data) => post('/api/appointment/create', data, true),
  cancel: (id) => post('/api/appointment/cancel', { id }, true)
}

添加文件上传

export const uploadFile = (filePath, url) => {
  return new Promise((resolve, reject) => {
    uni.uploadFile({
      url: baseUrl + url,
      filePath: filePath,
      name: 'file',
      header: {
        token: uni.getStorageSync('token')
      },
      success: (res) => {
        resolve(JSON.parse(res.data))
      },
      fail: (err) => {
        reject(err)
      }
    })
  })
}

常见问题

Q: 如何修改 API 地址？

A: 编辑 TUICallKit-Vue3/main.js 中的 baseUrl 变量。

Q: 如何添加自定义请求头？

A: 在 TUICallKit-Vue3/main.js 中的 header 对象中添加。

Q: 如何处理登录失效？

A: 当 code === -1 时，自动清除 token，可选择跳转到登录页。

Q: 如何取消请求？

A: 小程序不支持直接取消请求，可使用标志位实现。

Q: 如何处理文件上传？

A: 使用 uni.uploadFile 而不是 uni.request。

相关文件

• 全局配置: TUICallKit-Vue3/main.js
• API 服务: TUICallKit-Vue3/utils/api.js
• 首页组件: TUICallKit-Vue3/pages/index/index.vue
• API 配置: TUICallKit-Vue3/API_CONFIG.md
• API 使用指南: TUICallKit-Vue3/API_USAGE_GUIDE.md
• 后端控制器: server/app/api/controller/DoctorController.php
• 后端逻辑: server/app/api/logic/DoctorLogic.php

总结

已完成小程序与后端 API 的完整集成：

1. ✅ 后端 API 开发（医生列表、详情、排班）
2. ✅ 前端 API 服务层封装
3. ✅ 首页医生列表展示
4. ✅ 错误处理和加载状态
5. ✅ 文档和使用指南

小程序现在可以正常加载和展示医生列表。