网络请求 (Alova) 使用指南

本项目使用 Alova.js 作为网络请求库，基于 uniappRequestAdapter 适配了 UniApp 环境。所有的网络请求配置都集中在 src/api/core/ 目录下。

1. 核心特性

• 轻量高效: Alova 是一个轻量级的请求策略库。
• UniApp 适配: 使用 uniappRequestAdapter，兼容小程序、H5 和 App。
• 拦截器封装: 统一处理了 Token 注入、租户 ID、错误处理、登录过期跳转等逻辑。
• TypeScript 支持: 完整的类型提示。

2. 目录结构

src/api/
├── core/
│   ├── instance.ts      # Alova 实例创建与配置
│   ├── handlers.ts      # 响应与错误处理逻辑
│   └── middleware.ts    # 中间件 (如有)
├── user/                # 用户模块 API
├── product/             # 商品模块 API
├── order/               # 订单模块 API
└── ...

3. 定义 API

在 src/api/ 下对应的模块文件中定义接口函数。

3.1 基础 GET 请求

// src/api/user/user.ts
import { alovaInstance } from '@/api/core/instance'

// 获取用户信息
export function getUserInfo(id: string) {
  // 泛型 <User> 指定返回数据的类型
  return alovaInstance.Get<User>(`/mall-user/app/userinfo/${id}`)
}

3.2 带参数的 GET 请求

export function getGoodsList(params: { page: number; size: number }) {
  return alovaInstance.Get<GoodsList>('/product/app/goodsspu/page', {
    params, // 会被自动拼接到 URL 后面
  })
}

3.3 POST 请求

export function updateProfile(data: { nickname: string; avatar: string }) {
  return alovaInstance.Post<void>('/mall-user/app/userinfo/update', data)
}

3.4 跳过 Token 验证

如果某些接口（如登录、公开数据）不需要 Token，可以在 header 中配置 skipToken: true。

export function getPublicConfig() {
  return alovaInstance.Get<Config>('/public/config', {
    headers: {
      skipToken: true,
    },
  })
}

4. 在页面中使用

Alova 返回的是一个 Promise，可以直接使用 async/await 或 .then()。

<script setup lang="ts">
import { ref } from 'vue'
import { getGoodsList } from '@/api/product/spu'

const list = ref([])

async function loadData() {
  try {
    // 自动解包：response 已经是 data 字段的内容（拦截器已处理）
    const res = await getGoodsList({ page: 1, size: 10 })
    list.value = res.records
  } catch (error) {
    console.error('加载失败', error)
  }
}

onLoad(() => {
  loadData()
})
</script>

5. 拦截器逻辑说明

5.1 请求拦截 (beforeRequest)

位置: src/api/core/instance.ts

• Content-Type: 自动为 POST/PUT/PATCH 添加 application/json。
• Token: 从 useAuthStore 获取 Token 并添加到 Header (satoken)。
• Tenant ID: 自动添加租户 ID (tenant-id)。
• 客户端类型: 根据平台自动添加 client-type (WX_MA, APP, H5)。

5.2 响应拦截 (responded)

位置: src/api/core/handlers.ts

• 数据解包: 自动提取 response.data，直接返回业务数据。
• 业务错误: 如果 code !== 0，会抛出 ApiError 并自动弹出全局错误提示。
• 登录过期: 拦截 401/403 状态码，自动清除 Token 并跳转到登录页（防抖处理）。

6. 开发环境日志

在开发模式 (NODE_ENV=development) 下，控制台会输出详细的请求和响应日志：

• [Alova Request] GET /api/...
• [Alova Response] { code: 0, data: ... }

7. 常用配置项

在 src/api/core/instance.ts 中可以修改全局配置：

• timeout: 请求超时时间（默认 60000ms）。
• baseURL: 接口基础路径（读取 .env 文件）。