karamay/API_README.md

API 拦截器使用说明

概述

本项目已集成完整的 API 请求拦截器系统，包括：

• 统一的请求/响应拦截
• Token 自动管理
• 错误处理
• 接口代理配置

文件结构

src/
├── utils/
│   ├── request.js    # axios 拦截器配置
│   └── auth.js       # Token 管理工具
├── api/
│   └── index.js      # API 接口封装
└── components/
    └── ApiExample.vue # API 使用示例

配置说明

1. 代理配置 (vite.config.js)

server: {
  proxy: {
    '/api': {
      target: 'https://sit-kelamayi.4dage.com',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, '/api')
    }
  }
}

2. 需要 Token 的接口配置

在 src/utils/request.js 中的 needsTokenApis 数组中配置需要携带 token 的接口：

const needsTokenApis = [
  '/api/user', // 用户相关接口
  '/api/booking', // 预约相关接口
  '/api/activity/register', // 活动报名
  '/api/collection', // 收藏相关接口
]

API 使用方法

方式一：直接导入使用

import { museumApi, userApi } from '@/api'

// 获取轮播图（不需要token）
const carouselData = await museumApi.getCarouselList({
  pageNum: 1,
  pageSize: 5,
  status: 1,
})

// 获取用户信息（需要token）
const userInfo = await userApi.getUserInfo()

方式二：使用全局 API

// 在组件中
const { proxy } = getCurrentInstance()
const data = await proxy.$api.museumApi.getExhibitionList(params)

Token 管理

设置 Token

import { setToken, setUserInfo } from '@/utils/auth'

// 登录成功后
setToken(token, remember) // remember: true=localStorage, false=sessionStorage
setUserInfo(userInfo, remember)

检查登录状态

import { isLoggedIn, getToken } from '@/utils/auth'

if (isLoggedIn()) {
  // 已登录
  const token = getToken()
}

清除认证信息

import { clearAuth } from '@/utils/auth'

// 退出登录时
clearAuth()

接口列表

博物馆相关接口

• getCarouselList(params) - 获取轮播图列表
• getExhibitionList(params) - 获取展览列表
• getExhibitionDetail(id) - 获取展览详情
• getActivityList(params) - 获取活动列表
• getActivityDetail(id) - 获取活动详情
• getNewsList(params) - 获取新闻列表
• getNewsDetail(id) - 获取新闻详情

预约相关接口（需要 Token）

• createBooking(data) - 创建预约
• getBookingList(params) - 获取预约列表
• getBookingDetail(id) - 获取预约详情
• cancelBooking(id) - 取消预约

用户相关接口（需要 Token）

• getUserInfo() - 获取用户信息
• updateUserInfo(data) - 更新用户信息
• changePassword(data) - 修改密码

活动报名接口（需要 Token）

• registerActivity(data) - 报名活动
• getRegistrationList(params) - 获取报名列表
• cancelRegistration(id) - 取消报名

收藏相关接口（需要 Token）

• addCollection(data) - 添加收藏
• removeCollection(id) - 取消收藏
• getCollectionList(params) - 获取收藏列表

错误处理

拦截器会自动处理以下错误：

• 401/403: 自动清除 token，提示重新登录
• 404: 接口不存在
• 500: 服务器错误
• 网络错误: 网络连接失败

示例组件

查看 src/components/ApiExample.vue 了解完整的使用示例。

注意事项

1. Token 自动管理: 拦截器会自动在需要的接口中添加 Authorization 头
2. 错误统一处理: 所有 API 错误都会被拦截器捕获并统一处理
3. 请求时间戳: 自动为所有请求添加时间戳，防止缓存
4. 开发环境代理: 开发时通过 Vite 代理转发到测试服务器
5. 生产环境: 需要配置正确的 API 基础路径

扩展接口

如需添加新接口，请在 src/api/index.js 中添加：

// 添加新的接口分类
export const newApi = {
  // 新接口方法
  getNewData: (params) => request.get('/api/new/data', { params }),
  createNewData: (data) => request.post('/api/new/data', data),
}

// 如果需要 token，在 request.js 的 needsTokenApis 中添加路径