# 小程序 API 使用指南

## 概述

小程序使用统一的 API 请求方式，通过 `main.js` 中定义的全局 `apiUrl` 方法进行请求。

## 全局 apiUrl 方法

### 定义位置

`TUICallKit-Vue3/main.js` 中定义了全局的 `apiUrl` 方法：

```javascript
function apiUrl(promise, Loading = true) {
  const token = uni.getStorageSync('token')
  const header = {
    token: token,
    'content-type': 'application/x-www-form-urlencoded',
    ...(promise.header || {})
  }
  const data = promise.data || {}
  const url = baseUrl + (promise.url || '')
  
  return new Promise((resolve, reject) => {
    if (Loading) {
      uni.showLoading({ title: '加载中...', mask: true })
    }
    
    uni.request({
      url: url,
      data: data,
      timeout: 15000,
      method: promise.method || 'POST',
      header: header,
      sslVerify: false,
      success: (res) => {
        const data = res.data
        if (data.code === -1) {
          uni.removeStorageSync('token')
        }
        resolve(data)
      },
      fail: (e) => {
        reject(e)
      },
      complete: (e) => {
        if (Loading) {
          uni.hideLoading()
        }
      }
    })
  })
}
```

### 参数说明

| 参数 | 类型 | 说明 |
|------|------|------|
| promise.url | string | 请求URL（相对路径） |
| promise.method | string | 请求方法（GET/POST，默认POST） |
| promise.data | object | 请求数据 |
| promise.header | object | 自定义请求头 |
| Loading | boolean | 是否显示加载中（默认true） |

## API 服务层

### 文件位置

`TUICallKit-Vue3/utils/api.js`

### 基础方法

```javascript
// GET 请求
export const get = (url, data = {}, loading = false) => {
  return request(url, 'GET', data, loading)
}

// POST 请求
export const post = (url, data = {}, loading = true) => {
  return request(url, 'POST', data, loading)
}
```

### 医生 API

```javascript
export const doctorApi = {
  // 获取医生列表
  getDoctorList: (params) => get('/api/doctor/lists', params, false),
  
  // 获取医生详情
  getDoctorDetail: (id) => get('/api/doctor/detail', { id }, false),
  
  // 获取医生排班
  getDoctorRoster: (doctorId, date) => get('/api/doctor/roster', { doctor_id: doctorId, date }, false)
}
```

## 使用示例

### 1. 在组件中使用

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

const doctors = ref([])
const loading = ref(false)

// 获取医生列表
const fetchDoctors = async () => {
  loading.value = true
  try {
    const response = await doctorApi.getDoctorList({
      page_no: 1,
      page_size: 10
    })
    
    if (response && response.code === 1) {
      doctors.value = response.data.lists || []
    } else {
      uni.showToast({
        title: response.msg || '获取失败',
        icon: 'none'
      })
    }
  } catch (error) {
    console.error('请求失败:', error)
    uni.showToast({
      title: '网络错误',
      icon: 'none'
    })
  } finally {
    loading.value = false
  }
}

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

### 2. 创建新的 API 模块

```javascript
// utils/api.js 中添加

export const appointmentApi = {
  // 获取预约列表
  getAppointmentList: (params) => get('/api/appointment/lists', params, false),
  
  // 创建预约
  createAppointment: (data) => post('/api/appointment/create', data, true),
  
  // 取消预约
  cancelAppointment: (id) => post('/api/appointment/cancel', { id }, true)
}
```

### 3. 使用自定义请求头

```javascript
import { request } from '../utils/api'

// 发送带自定义请求头的请求
const response = await request(
  '/api/custom/endpoint',
  'POST',
  { data: 'value' },
  true,
  { 'X-Custom-Header': 'custom-value' }
)
```

## 响应格式

### 成功响应

```json
{
  "code": 1,
  "msg": "success",
  "data": {
    "lists": [...],
    "count": 10,
    "page_no": 1,
    "page_size": 10
  }
}
```

### 失败响应

```json
{
  "code": 0,
  "msg": "错误信息"
}
```

### 登录失效

```json
{
  "code": -1,
  "msg": "登录已失效"
}
```

当 `code === -1` 时，会自动清除 token。

## 错误处理

### 自动处理

- 登录失效（code === -1）：自动清除 token
- 网络错误：自动显示加载中/隐藏加载中

### 手动处理

```javascript
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)
  uni.showToast({
    title: '网络错误，请检查连接',
    icon: 'none'
  })
}
```

## 配置说明

### 基础 URL

在 `main.js` 中定义：

```javascript
var baseUrl = 'http://api.zzzhengyangtang.cn'
```

修改此值来改变 API 基础地址。

### 超时时间

在 `main.js` 中的 `uni.request` 中定义：

```javascript
timeout: 15000  // 15秒超时
```

### 请求头

默认请求头：

```javascript
{
  token: 'user_token',
  'content-type': 'application/x-www-form-urlencoded'
}
```

## 常见问题

### Q: 如何添加新的 API？

A: 在 `utils/api.js` 中添加新的 API 对象：

```javascript
export const newApi = {
  getList: (params) => get('/api/new/lists', params, false),
  create: (data) => post('/api/new/create', data, true)
}
```

### Q: 如何修改请求头？

A: 在 `request` 函数中修改 `header` 对象，或在调用时传入自定义请求头。

### Q: 如何处理文件上传？

A: 使用 `uni.uploadFile` 而不是 `uni.request`：

```javascript
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: 如何取消请求？

A: 小程序的 `uni.request` 不支持直接取消，但可以使用标志位：

```javascript
let requestAborted = false

const fetchData = async () => {
  const response = await doctorApi.getDoctorList({ page_no: 1 })
  
  if (requestAborted) {
    return
  }
  
  // 处理响应
}

// 取消请求
const abortRequest = () => {
  requestAborted = true
}
```

## 最佳实践

1. **统一 API 管理**：所有 API 调用都通过 `utils/api.js` 进行
2. **错误处理**：始终使用 try-catch 处理异步请求
3. **加载状态**：在请求时显示加载中，完成后隐藏
4. **响应验证**：检查 `code` 字段判断请求是否成功
5. **token 管理**：自动处理 token 过期情况

## 相关文件

- API 服务: `TUICallKit-Vue3/utils/api.js`
- 全局配置: `TUICallKit-Vue3/main.js`
- 首页示例: `TUICallKit-Vue3/pages/index/index.vue`
- API 配置: `TUICallKit-Vue3/API_CONFIG.md`