外观
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 | 业务失败,或项目显式创建的业务错误 |
http | HTTP 状态失败,code 为 HTTP 状态码 |
network | 网络或连接错误 |
timeout | 传输超时,code 为 408 |
cancelled | 客户端取消,本地 code 为 499 |
config | 配置或序列化错误 |
isRequestCanceled() 识别模板取消、Axios 取消和 AbortError;旧 handleError() 继续转换并抛出 HttpError。
迁移时,依赖“默认取消重复请求”的调用需显式设置 cancelPrevious;依赖全局写请求重试的调用需逐项确认幂等后配置。普通请求方法、响应结果和消息开关无需重写。