useApi

一个基于 Axios 的强类型 API 请求工具类，提供统一的请求处理、错误处理和类型推导。

完整的类型支持

useApi 提供完整的 TypeScript 类型推导，通过定义接口类型映射，可以在开发时获得精确的参数提示和返回值类型。

项目文件

loading

初始化

在应用入口处（如 src/api/index.ts）初始化 ApiService：

loading

项目结构

推荐的项目结构组织方式：

api/
├── index.ts                # API 实例初始化和导出
├── global-types.d.ts       # 全局类型定义
├── modules/               # API 模块
│   ├── user.ts           # 用户相关接口
│   └── app.ts            # 应用相关接口
└── types/                # 类型定义
    ├── user.ts           # 用户模块类型
    ├── app.ts            # 应用模块类型
    └── index.d.ts        # 类型导出

快速开始

1. 初始化

在 src/api/index.ts 中初始化 ApiService：

import type { AppApi } from './types'
import { ApiService } from '@qxs-bns/utils'
import axios from 'axios'

// 创建 axios 实例
const axiosInstance = axios.create({
  baseURL: '/api',
  timeout: 10000
})

// 创建 API 服务实例
export const api = new ApiService<AppApi>(axiosInstance, false)

2. 定义类型

在 src/api/types/index.d.ts 中定义接口类型：

import type { ApiTypeMap, UrlObjectType } from '@qxs-bns/utils'

// 定义 URL 配置
export interface AppUrlObject extends UrlObjectType {
  url: '/user/list' | '/user/detail'
  method: 'GET' | 'POST'
}

// 定义接口映射
export interface AppApi extends ApiTypeMap<AppUrlObject> {
  '/user/list': {
    request: { page: number, size: number }
    response: User[]
  }
  '/user/detail': {
    request: { id: number }
    response: User
  }
}

3. 使用示例

import { api } from '@/api'

// GET 请求
const { res, error } = await api.useApi({
  url: '/user/list',
  method: 'GET',
  params: {
    page: 1,
    size: 10
  }
})

// POST 请求
const { res, error } = await api.useApi({
  url: '/user/detail',
  method: 'POST',
  data: {
    id: 1
  }
})

API 参考

ApiService 配置项

参数	说明	类型	必填	默认值
apiInstance	Axios 实例	AxiosInstance	是	-
isWholeResponse	是否返回完整响应	boolean	是	false

请求配置

参数	说明	类型	必填	默认值
url	请求地址	string	是	-
method	请求方法	'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'	是	-
params	GET 请求参数	object	否	-
data	请求体数据	object	否	-
proxyPrefix	代理前缀	string	否	-

响应类型

// 基础响应类型
interface UseApiResponse<W extends boolean = false, T = unknown> {
  res: W extends true ? SuccessResponse<T> : T
  error: ErrorResponse | null
}

// 成功响应
interface SuccessResponse<T> {
  code: number // 响应码
  count: number // 数据总数
  data: T // 响应数据
  message: string // 响应消息
}

// 错误响应
interface ErrorResponse {
  code: number // 错误码
  data: null // 错误数据
  message: string // 错误信息
}

高级特性

完整响应模式

当需要获取完整的响应信息时，可以：

// 方式一：实例级别设置
const api = new ApiService(axiosInstance, true)

// 方式二：请求级别设置
const { res, error } = await api.useApi(config, params, true)

错误处理

ApiService 内置了完整的错误处理机制：

1. HTTP 错误（非 200 状态码）
2. 业务错误（code 非 0）
3. 网络错误
4. 请求超时

所有错误都会被统一处理并通过 error 对象返回。

代理前缀

支持为不同的请求配置不同的代理前缀：

const { res } = await api.useApi({
  url: '/user/list',
  method: 'GET',
  proxyPrefix: '/api/v1' // 会被添加到 url 前面
})

最佳实践

1. 按模块组织 API：

// api/modules/user.ts
export const userApi = {
  getList: params => api.useApi({
    url: '/user/list',
    method: 'GET',
    params
  }),
  getDetail: id => api.useApi({
    url: '/user/detail',
    method: 'POST',
    data: { id }
  })
}

2. 使用类型别名简化类型定义：

type ApiRequest<T extends keyof AppApi> = AppApi[T]['request']
type ApiResponse<T extends keyof AppApi> = AppApi[T]['response']

3. 统一的错误处理：

const { res, error } = await api.useApi(...)
if (error) {
  // 统一错误处理
  handleError(error)
  return
}