前端请求方案选型:fetch、Axios 与服务端状态管理(1):HTTP 客户端与请求封装的边界
- HTTP 客户端与请求封装的边界(当前)
- 查询缓存、数据身份与写后同步
- React、Vue 与 Nuxt 的数据工具选型
用户列表页需要加载数据,搜索框需要在输入变化后重新请求,编辑资料后还要更新详情和列表。第一次实现时,每个功能都可以从一个 fetch() 开始;等这些功能放到同一个应用里,问题就逐渐变成了:两个组件会不会重复请求,页面回来时能不能先显示旧数据,保存成功后哪些地方需要更新。
这些问题经常被一起归进「请求封装」。于是,原生 fetch、Axios、React Query、SWR、各种 useRequest 都出现在同一份选型清单里。它们确实都和请求有关,但承担的职责不同。底层换成 fetch,可以改变请求客户端的实现;数据的共享、过期和修改后的同步,还需要另一组规则。
《为什么我在团队里禁止使用 axios?》提出了一个值得讨论的方向:现代 fetch 已经能够承担大量业务请求,项目可以重新评估对 Axios 的依赖。不过,是否使用 Axios、是否自己维护通用请求封装、是否引入服务端状态管理,是可以分别作出的决定。每项决定都对应不同的收益与维护责任。
能力与文档核对于 2026-10-21。示例围绕现代 Web 应用,TanStack Query 使用 v5 API;旧 WebView、小程序、React Native 和不同服务端运行时,需要另外核对对应适配器。代码片段用于解释职责和关键行为,不是一套可以覆盖全部接口协议的通用请求实现。
发出请求与管理数据,是两组职责
以读取用户资料为例,浏览器原生 API 的直接写法很短:
const response = await fetch('/api/users/42', {
headers: { Accept: 'application/json' },
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
const user = await response.json();
这里完成了网络请求、HTTP 状态检查和响应解析。fetch 在收到 404、500 等 HTTP 响应时不会自动 reject,请求函数需要决定哪些状态应当转成错误;网络失败、取消以及后续的解析失败,也可能使相应 Promise 拒绝。Fetch 的错误与响应处理规则解释了这些阶段的区别。
把它放进组件后,还需要决定请求何时执行,加载期间展示什么,失败后能否重试。再增加一个同时展示相同用户的组件,就会碰到数据共享和请求去重。编辑完成后,详情与不同筛选条件下的列表又可能同时过期。
下图展示一种常见的职责分层,箭头表示调用关系。简单页面可以直接调用请求函数;需要共享缓存的应用,再让数据管理层承接组件订阅。
请求客户端负责一次 HTTP 交互,包括 URL、请求头、请求体、响应解析、超时、取消,以及约定好的错误转换。原生 fetch、Axios、Ky、ofetch 都可以参与这一层;后三者会提供更多现成行为。
异步操作管理负责执行时机和执行状态,包括自动或手动调用、loading、error、防抖、节流、轮询等。React 的 ahooks useRequest、VueRequest 和 VueUse 的部分工具,适合从这类需求切入。
服务端状态管理负责远程数据在前端的副本,包括缓存身份、新鲜程度、跨组件订阅、后台刷新,以及写操作后的更新与失效。TanStack Query、SWR、Pinia Colada 和 RTK Query 都覆盖了这类问题。
这里的服务端状态指由远程系统持有、前端通过异步操作获取和修改的数据。用户资料、订单列表、库存都属于这一类。弹窗是否打开、搜索框尚未提交的输入、编辑中的表单,则通常属于客户端状态。
这些分类允许能力重叠。useRequest 也可能提供缓存,Query 库也会管理 loading 和轮询。比较时应当看项目需要哪组行为,而不能只凭函数名判断。
fetch 封装与成熟请求客户端
现代 fetch 提供了统一的请求与响应模型,能够配合 AbortController、AbortSignal、Headers、URL 和 Streams API 使用。对接口数量少、协议稳定的应用,一层范围明确的封装可以很合适。需要评估的是封装承诺的范围,以及范围扩大以后谁来维护边界。
一份简短封装隐含了哪些接口约定
下面这些行为看起来都很普通,却对应不同的契约:
| 封装中的默认行为 | 它隐含的约定 |
|---|---|
所有响应都调用 json() |
每个成功响应都有合法 JSON |
所有请求都设置 JSON Content-Type |
请求体都按 JSON 发送 |
自动返回 body.data |
所有接口共享同一种响应外层 |
| HTTP 200 就返回成功 | 业务失败不会放在成功状态码里 |
| 超时或错误后重发 | 请求允许被再次执行,请求体也能再次发送 |
| 自动读取浏览器存储中的 Token | 调用发生在浏览器,且认证确实采用这一来源 |
这些约定可以成为项目规范,但不宜静默扩展到文件下载、204 空响应、FormData、SSE 和服务端请求。比如,用 response.json() 包装所有请求,会在解析前等待整个 JSON 响应完成;要逐步消费流式内容,需要使用响应体的 reader 或对应的流解析器。
请求头也有真实的数据结构。RequestInit.headers 接受普通对象、键值对数组和 Headers 实例,直接用对象展开合并,并不能正确覆盖所有输入。可以先通过 new Headers(input) 归一化,再使用 set()、has() 等方法操作。上传 FormData 时,应让浏览器生成 multipart 的 Content-Type 和 boundary。FormData 的发送说明明确提醒了这一点。
错误通常也需要区分层次。网络失败表示没有获得可用响应;HTTP 错误表示响应状态不符合约定;业务错误可能藏在 HTTP 200 的 JSON 中;解析或校验失败则说明响应不能按预期消费。取消请求是否展示错误提示,又是界面的选择。请求层可以把这些差异转换成稳定错误对象,界面根据错误类别决定交互。
TypeScript 泛型只影响开发阶段的类型判断。request<User>() 或 response.json() as Promise<User> 都不会在运行时检查服务端是否真的返回了 User。如果外部响应的可信度影响后续逻辑,可以在接口函数边界加入 schema 校验,而不是把泛型当作校验结果。
超时、取消和旧结果覆盖
下面这行代码很容易出现在自建封装里:
const signal = config.signal ?? AbortSignal.timeout(10_000);
它表达的是二选一。调用方一旦传入 signal,默认超时就不再参与。现代运行时可以使用 AbortSignal.any()组合取消来源:
const timeoutSignal = AbortSignal.timeout(10_000);
const signal = config.signal ? AbortSignal.any([config.signal, timeoutSignal]) : timeoutSignal;
const response = await fetch(url, { ...config, signal });
这里的 config 指标准 RequestInit,只展示信号组合。需要兼容旧运行时时,应核对 timeout()、any() 的支持范围;使用定时器兜底的实现,还要处理定时器和事件监听的清理。AbortSignal.timeout()采用 active time 语义,浏览器暂停页面等情况也会影响计时,不能把它理解成服务端业务执行时限。
搜索框还会遇到另一个问题。搜索词 A 的请求先发出,搜索词 B 后发出;如果 A 最后返回,旧结果可能覆盖新结果。取消 A 可以减少无用工作,界面仍然需要明确结果属于哪个搜索条件。查询 key、执行序号或其他身份判断,负责保护结果归属。
调用某个工具返回的 cancel(),也不能仅凭名字就认定网络已经中断。它可能取消尚未执行的防抖任务,也可能让当前结果不再生效;真正终止 fetch,需要把对应 signal 传到网络调用。TanStack Query 的取消文档同样区分了默认缓存行为和消费取消信号后的行为。前端中断网络等待,也不代表服务端已经撤销写操作。
Token 刷新仍然需要系统自己的规则
几个请求同时返回 401 时,复用一个正在进行的 refresh Promise,可以减少重复刷新。这个机制适用于 fetch,也适用于 Axios 拦截器。
不过,「当前有刷新任务就等待它」只处理了重叠发生的刷新。假设请求 A 已经完成刷新,刷新锁也释放了,请求 B 携带旧 Token 的 401 此时才到达。B 如果只看锁是否为空,就可能再次刷新。请求层还需要比较发出请求时的认证版本与当前认证版本,判断是否已经有更新的凭据可用于一次重发。
认证链路也应明确刷新失败怎样结束会话、原请求最多重发几次、取消与总耗时怎样计算,以及请求体是否可重放。JSON 字符串可以重新发送,已经消费的流式请求体通常不能直接复用;Fetch 对请求体的说明给出了只能消费一次的例子。
服务端渲染时,认证来源和刷新协调要绑定当前请求或会话。浏览器里的 localStorage、模块级的单个 refresh Promise,都不能直接照搬成服务所有访问者的认证实现。选择哪个 HTTP 客户端,并不会替项目完成这些系统约束。
Axios 也可以使用 fetch
Axios 的 fetch adapter 从 v1.7.0 就已经加入,可以明确选择:
import axios from 'axios';
const client = axios.create({ adapter: 'fetch' });
const response = await client.get('/api/events', {
responseType: 'stream',
});
这个片段只说明适配器与响应类型,流的消费和 SSE 事件解析需要继续实现。stream 是否可用,仍取决于对应环境。把 Axios 一概描述成只支持浏览器 XHR 和 Node HTTP,会漏掉当前能力;它也已经支持通过 signal 接入 AbortController。
拦截器是否容易调试,则取决于职责组织。鉴权、日志、灰度和错误转换放进多个隐式拦截器里可能混乱,全部写进一个很长的 fetch 函数也可能混乱。明确执行顺序、保留错误原因、限制响应变形,比简单统计拦截器数量更有帮助。
Ky、ofetch 和自有封装的取舍
基于 fetch 的成熟客户端提供了一个折中方案。项目继续采用 Web 标准的请求模型,同时复用通用能力。
- Ky 提供 JSON 请求选项、HTTP 错误处理、超时、重试、hooks 和可配置实例。它适合希望使用 fetch 语义、又不想反复维护通用行为的现代 Web 项目。采用时要按安装版本阅读文档,尤其注意 hooks 和 URL 选项的版本变化。
- ofetch 提供自动响应解析、
baseURL、query、超时和请求生命周期拦截器。它与 Nuxt 的技术生态接近,也可以独立使用。偏好直接返回解析结果、集中配置请求默认值的项目,可以优先评估。 - Axios 适合已经有统一规范、插件依赖或适配需求的团队。浏览器上传进度需要按适配器与目标环境验证;如果明确需要 XHR 的上传进度事件,可以保留相应请求通道。
- 原生 fetch 加自有封装 适合约定很窄、依赖预算明确、维护责任清楚的项目。接口类型增加时,重新评估封装范围,不必持续把所有能力都扩充进同一个函数。
这些客户端默认行为并不一致。例如 ofetch 默认会对符合条件的失败请求重试,但默认不重试 POST、PUT、PATCH、DELETE;Ky 也有自己的重试方法与状态码集合。选型时应阅读对应版本的默认值,而不是假设引入库后行为仍等同于一次原生 fetch。
项目再包一层时,可以只保留自己的 API 地址、认证接入、业务错误和观测约定。缓存订阅、页面 loading、弹窗提示等职责各有自己的使用场景,不宜继续集中到请求客户端中。
协议、类型与跨端需求也会改变候选
如果请求层还要覆盖多端适配、API 代码生成或实体级缓存,仅比较 fetch 与 Axios 的调用方式就不够了。这些需求会改变接口函数的来源和数据管理方式。
alova覆盖请求适配和更多请求策略,包括不同框架接入、分页、认证、重试与 SSE 等。希望采用较完整请求方案的团队,可以评估它;已有客户端与缓存规范的项目,则应计算替换和重叠成本,不必为了功能清单更长就重新组织所有接口。
后端提供可靠 OpenAPI 时,openapi-fetch可以配合生成的类型获得路径、参数与响应的类型提示;Orval还能生成不同客户端形式及 React Query、Vue Query 等集成代码。这里首先要确认接口文档是否准确、业务错误怎样表达、生成代码怎样更新,以及生成层与自定义认证层在哪里衔接。
代码生成改善的是契约同步与重复劳动,运行时仍然可能收到不符合文档的数据。需要验证的边界,继续使用运行时校验,而不能因为接口代码由工具生成就默认全部可信。
GraphQL 应用还可以比较 Apollo Client、urql等专用客户端。它们提供的协议、订阅和缓存模型,可能比给普通 HTTP 请求增加一层统一包装更贴合需求。
小程序、React Native 和 App WebView 则需要分别确认网络入口、上传下载、Cookie、证书和取消能力。浏览器 API 标准化降低了迁移成本,却不能保证每一种宿主环境都具备相同的运行条件。
总结
fetch 已经足以成为现代 Web 请求层的基础。是否继续采用 Axios,主要取决于现有约定、适配器、插件和维护成本;是否采用 Query 库,则取决于远程数据怎样被共享、重新验证和修改。把数据身份、生命周期与写后同步规则确定下来,请求客户端才有一个清楚而稳定的职责范围。
下一篇:查询缓存、数据身份与写后同步。