Skip to content

HTTP 请求契约 ​

入口为 src/utils/http/index.ts。保留 api.get/post/put/del/request 及 { code, data, message/msg } 响应解包:业务成功码支持 0、200 及其数字字符串,HTTP 204 和 HEAD 响应返回 undefined。下载等其他响应格式仍由项目单独适配。

默认行为 ​

  • 默认并行,不自动取消另一组件或同一接口的请求。
  • 默认不重试;全局 VITE_HTTP_MAX_RETRIES 仅为 GET/HEAD 配置额外尝试次数。
  • 取消会拒绝 Promise,但不显示错误、不重试。
  • 中间失败不弹错误,重试结束后按 showErrorMessage 提示一次。
  • showSuccessMessage 仍默认关闭,仅最终成功时提示一次。

取消与表格接入 ​

ts
import api, { isRequestCanceled } from '@/utils/http'

const controller = new AbortController()
const pending = api.get({ url: '/services', signal: controller.signal })
controller.abort()
try {
  await pending
} catch (error) {
  if (!isRequestCanceled(error)) throw error
}

调用方的信号连接到请求管理器,不会被覆盖。已取消的信号不发起请求,也不替换有效请求。请求结束时清理监听器和记录。

搜索表格的请求参数已包含 signal。替换 Mock 时,应将其传递给 api.get({ url, params, signal }),并将结果适配为 { records, total }。表格用请求序号忽略旧结果,传递信号还可以停止无效传输与重试等待。页面离开或组件卸载等取消时机由调用方控制。

显式替换旧请求 ​

ts
// 在组件 setup 中创建,各组件独立;不要在每次请求时重新创建。
const scope = Symbol('service-search')

api.get({
  url: '/services',
  params: { keyword },
  cancelPrevious: true,
  requestScope: scope,
  requestKey: 'latest-search'
})

显式开启后,同一 scope、同一 key 的新请求取消旧任务,包括重试等待。省略 scope 时使用 global,无关组件应使用不同 scope。

省略 key 时,按方法、基础地址、URL、参数、请求体、响应模式、鉴权和请求头生成稳定 key;属性顺序不影响比较,类型和分隔符不会混淆。不同参数不会自动相互取消。上例的显式 key 则表示不同关键词也只保留最新查询。

FormData、Blob、ArrayBuffer、类实例、循环数据、自定义参数或请求体转换器跳过自动比较,正常发送。确需替换上传任务时显式提供 key 和 scope,不读取或哈希文件内容。

客户端取消不能撤销服务端已执行的操作。写请求防重复提交还需页面提交状态和后端幂等机制。

重试 ​

ts
api.get({ url: '/services', retry: { retries: 2, delay: 1000 } }) // 最多 3 次
api.get({ url: '/services', retry: false }) // 关闭该请求的全局重试

GET/HEAD 仅针对网络错误、传输超时和 HTTP 408、500、502、503、504 重试。HTTP 401/403、其他状态、业务失败和配置错误不自动重试。业务响应中的 code: 500 不等同于 HTTP 500。

POST/PUT/DELETE 等方法默认不重试,全局设置不改变这一点。确认后端具有幂等保障、请求体可重复发送后,才按请求显式开启:

ts
api.post({
  url: '/operations',
  data: operation,
  headers: { 'Idempotency-Key': operationId }, // 需后端支持,所有尝试复用此键
  retry: { retries: 1, delay: 1000, allowUnsafe: true }
})

具有退出登录等副作用的 GET 也应配置 retry: false。等待期间取消会清除计时器,不再发送下一次尝试。

会话清理 ​

cancelAllPendingRequests() 仍从 HTTP 入口导出,覆盖发送及重试等待中的所有任务。

退出开始时取消旧请求;清理认证状态、建立新会话或更换访问令牌时使旧任务失效。旧传输即使忽略取消并迟到返回,也不会交付该响应或用其 401 清理新会话。新请求使用独立控制器。旧退出任务结束时也不会清除后来建立的新会话。

正常的 HTTP/业务 401 仍清理会话,防抖只控制通知,不会跳过后续会话的失效处理。

错误与兼容 ​

HttpError 保留 code、data、URL、方法和日志结构,增加 kind:

kind含义
business业务失败,或项目显式创建的业务错误
httpHTTP 状态失败,code 为 HTTP 状态码
network网络或连接错误
timeout传输超时,code 为 408
cancelled客户端取消,本地 code 为 499
config配置或序列化错误

isRequestCanceled() 识别模板取消、Axios 取消和 AbortError;旧 handleError() 继续转换并抛出 HttpError。

迁移时,依赖“默认取消重复请求”的调用需显式设置 cancelPrevious;依赖全局写请求重试的调用需逐项确认幂等后配置。普通请求方法、响应结果和消息开关无需重写。