@iap/http

基于 Alova.js 封装的企业级 HTTP 请求库，提供统一响应结构、请求/响应拦截器、超时处理与 ACK 重试能力。

安装

pnpm add @iap/http
Copy

快速上手

import { createHttp } from '@iap/http'

const http = createHttp({ baseUrl: 'https://api.example.com' })

const res = await http.get<User[]>('/users')
console.log(res.data) // User[]
Copy

API

createHttp(instanceConfig?)

创建一个 HTTP 实例，所有配置项均为可选。

const http = createHttp({
  baseUrl: 'https://api.example.com',
  timeout: 10_000,
  headers: { 'X-App-Version': '1.0.0' },
  onRequest: (config) => {
    return { ...config, headers: { ...config.headers, Authorization: `Bearer ${token}` } }
  },
  onResponse: (res) => {
    if (res.code !== 200) throw new Error(res.message)
    return res
  },
  onError: (error, config) => {
    console.error(`请求失败: ${config.url}`, error)
  },
})
Copy

实例配置（HttpInstanceConfig）

HTTP 方法

http.get<T>(url, config?)
http.post<T>(url, body?, config?)
http.put<T>(url, body?, config?)
http.patch<T>(url, body?, config?)
http.delete<T>(url, config?)
http.request<T>(config)   // 完整控制
Copy

所有方法均返回 Promise<HttpResponse<T>>。

响应结构（HttpResponse<T>）

interface HttpResponse<T = unknown> {
  code: number        // 200 表示成功，-1 表示错误/超时
  message: string
  data: T
  timestamp: number
  description: string
  etag: string
  status?: string     // 'error' | 'timeout'（仅在失败时存在）
}
Copy

请求配置（HttpConfig）

ACK 重试

请求超时时，ACK 重试会以逐步增大的超时时间自动重发请求，适用于响应较慢或网络不稳定的场景。

const res = await http.get('/slow-endpoint', {
  timeout: 2000,
  ackRetry: true,
  ackRetryCount: 3,        // 最多重试 3 次
  ackRetryTimeoutRatio: 2, // 每次超时翻倍：2s → 4s → 8s → 16s
})
Copy

请求取消

传入 AbortSignal 可手动取消进行中的请求：

const controller = new AbortController()

const res = http.get('/data', { signal: controller.signal })

// 取消请求：
controller.abort()
Copy

工具函数

以下函数已导出，可在拦截器或自定义逻辑中使用：

import { createErrorResponse, createTimeoutResponse, isTimeoutError } from '@iap/http'
Copy

类型导出

import type {
  HttpConfig,
  HttpInstance,
  HttpInstanceConfig,
  HttpMethod,
  HttpResponse,
  RequestInterceptor,
  ResponseInterceptor,
  ErrorInterceptor,
} from '@iap/http'
Copy