前端请求方案选型:fetch、Axios 与服务端状态管理(2):查询缓存、数据身份与写后同步
- HTTP 客户端与请求封装的边界
- 查询缓存、数据身份与写后同步(当前)
- React、Vue 与 Nuxt 的数据工具选型
请求函数负责完成一次网络交互,多个组件共享远程数据时,还需要定义数据身份、新鲜度与写后同步。这里沿着用户详情和列表讨论服务端状态管理,底层 fetch、Axios、Ky 与 ofetch 的取舍见第一篇。示例继续使用 TanStack Query v5,能力与文档范围沿用 2026-10-21 的记录。
服务端状态管理增加了什么
一个请求函数可以被任意组件调用,但组件各自调用时,并不会自然共享结果。请求完成后把对象存在某个全局变量里,也还没有定义新鲜度、订阅、刷新和释放规则。服务端状态库把这些行为组织成可配置的缓存模型。
查询 key 定义数据身份
以 TanStack Query 为例,query key 是一份查询结果的身份。相同 QueryClient 中,使用相同 key 的查询可以订阅同一份缓存;影响结果的条件要进入 key。查询 key 文档要求把查询函数依赖的变量包含在其中。
const detailKey = ['users', 'detail', '42'];
const activeListKey = ['users', 'list', { status: 'active', page: 1 }];
const disabledListKey = ['users', 'list', { status: 'disabled', page: 1 }];
这三份数据有关联,却有不同身份。只用 ['users'] 缓存所有请求,会把详情、分页和不同筛选条件混在一起。语言、租户或当前账号会改变结果时,也应有明确的缓存隔离策略;认证凭据本身不适合作为缓存 key,账号切换时则需要处理旧的受保护数据。
相同 key 能复用正在进行的查询,并不表示任意时间再次订阅都不会产生新请求。是否重新获取,还取决于数据新鲜度、挂载与刷新策略等条件。
新鲜度与缓存回收是两个时间
缓存存在时,界面可以先使用已有数据,再决定是否需要重新验证。下图展示常见的过期后重新验证过程;轮询、显式刷新和特殊配置需要另外考虑。
staleTime 定义数据的新鲜期。在通常的配置下,新鲜期内不需要因为普通的挂载或窗口聚焦再次验证;过期以后,缓存可以继续展示,只是在符合触发条件时允许重新获取。时间走完本身不会创建一个周期请求,定时刷新由 refetchInterval 之类的配置负责。
gcTime 定义无订阅者的缓存保留时间。当某份查询没有活跃订阅者后,它才进入这类回收计时。它控制后续还能否复用缓存,不负责判断数据是否新鲜。
例如,设置 staleTime: 30_000、gcTime: 5 * 60_000,含义是数据通常在 30 秒内视为新鲜,没有订阅者后缓存可以保留 5 分钟。离开页面 40 秒后返回时,旧缓存可能还在,界面可以先展示它,再按策略后台刷新。这不等于每 30 秒自动请求,也不等于 30 秒后删除数据。
TanStack Query v5 的默认设置比较积极,查询数据默认视为 stale,无活跃订阅者的查询默认在 5 分钟后回收;重新挂载、窗口重新聚焦和网络恢复,可能触发过期查询的后台刷新。项目应根据数据变化频率和请求成本配置这些行为。默认值文档还区分了轮询与新鲜度的关系。
已有数据时的后台刷新,也应与第一次加载分开。第一次没有可展示数据,可以使用骨架或空白加载态;已有数据时,通常保留内容并提示正在刷新。后台刷新失败是否继续展示旧数据,要结合业务有效性决定,不能用一个 loading 布尔值把内容反复清空。
Query 缓存与 HTTP 缓存各有作用
浏览器可能已经按 Cache-Control、ETag 等机制缓存 HTTP 响应,Query 库仍然有用,因为两层缓存管理的对象不同。
| 机制 | 管理的对象 | 典型行为 |
|---|---|---|
| HTTP 缓存 | HTTP 响应及验证信息 | 强缓存、条件请求、304 |
| Query 缓存 | 应用查询结果与订阅状态 | 共享数据、标记过期、后台刷新 |
| 客户端状态 | 应用本地交互数据 | 表单草稿、弹窗、未提交筛选 |
Query 层判断需要重新获取后,底层请求仍可能命中浏览器 HTTP 缓存。反过来,浏览器有缓存也不会自动告诉应用:保存用户资料以后,哪些列表应标记过期。HTTP 缓存的命中与重新验证规则,可以对照 HTTP caching。
保存成功后,哪些缓存需要更新
编辑用户资料时,服务端写入成功只是一个阶段。详情、列表、搜索结果和统计数据,可能都受到影响;应用需要表达这些关联。Query 库提供执行机制,具体关联仍由业务定义。
下图是一种常见策略,前提是更新接口返回完整详情。详情可以直接写入返回值,列表则重新验证,因为修改可能改变其成员、排序或分页。
下面的 Vue 片段只展示写成功后的处理,updateUser 是项目提供的异步接口函数,返回包含 id 的完整用户详情。代码位于已经安装 VueQueryPlugin 的组件 setup 或 composable 中:
import { useMutation, useQueryClient } from '@tanstack/vue-query';
import { updateUser } from './user-api';
const queryClient = useQueryClient();
const mutation = useMutation({
mutationFn: updateUser,
onSuccess: async (user) => {
queryClient.setQueryData(['users', 'detail', user.id], user);
await queryClient.invalidateQueries({
queryKey: ['users', 'list'],
});
},
});
setQueryData 更新一份确定的查询结果;invalidateQueries 可以按 key 前缀匹配多份查询,将它们标记过期,并按默认规则重新获取活跃查询。没有订阅者的列表通常留到之后使用时再获取,不能把「失效」理解成马上重取应用里所有列表。失效规则与使用 mutation 返回值更新缓存分别说明了这两种操作。
如果更新接口只返回少数字段,就不能直接用它替换完整详情。可以按明确契约合并,也可以把详情标记过期。合并时要创建新对象,避免就地修改缓存里被多个订阅者使用的对象。表单需要编辑时,也可以建立独立草稿,保存后再通过明确入口更新查询数据。
列表尤其不能只按 ID 修改一行就认定完成同步:用户从 active 改为 disabled 后,可能要移出当前列表,另一份列表还要增加条目,总数与分页也可能变化。
乐观更新是在服务端确认前先更新界面,使操作看起来更快。它同时引入了失败回滚、并发写入、旧请求覆盖和最终重新验证的问题。不能只加一段本地赋值,就省略失败路径。
TanStack Query 主要按查询保存结果,不会因为几个返回对象恰好有同一个 ID,就自动维护所有副本。若应用需要实体级归一化缓存,可以比较 Apollo Client 等 GraphQL 客户端提供的数据模型。
在 React 项目中,管理一次异步操作的执行状态,与在组件间共享远程数据,是两类不同的需求。已有 Redux 的项目还应计算新增另一套缓存与数据层的成本。完整内容见React、Vue 与 Nuxt 工具选型。
Vue 的响应式请求工具和查询缓存不是同一种能力。Nuxt 页面取数先核对框架入口;需要进一步共享缓存时,再确定数据由哪套机制维护,并检查响应式 key 与 SSR 隔离。完整内容见React、Vue 与 Nuxt 工具选型。
新项目的默认选择与验证方式
选型应当在候选职责已经清楚之后,回到应用的数据关系。独立请求、共享查询、复杂写后同步和框架 SSR,会把项目引向不同组合。
| 项目条件 | 优先评估的方案 |
|---|---|
| 少量独立请求,主要管理局部状态 | 原生 fetch 或成熟客户端,配局部异步工具 |
| Vue SPA,共享查询和写后同步较多 | TanStack Vue Query + ofetch、Ky 或 Axios |
| Vue / Pinia 团队,重视 Vue 与路由集成 | Pinia Colada + 请求客户端 |
| React SPA,查询与 mutation 较复杂 | TanStack React Query + 请求客户端 |
| React,偏好简洁的缓存与重新验证入口 | SWR + fetcher |
| 已采用 Redux Toolkit | RTK Query |
| Nuxt 普通页面取数与首屏渲染 | 框架的 useFetch / useAsyncData / $fetch |
| 防抖、轮询、手动执行是主要需求 | ahooks useRequest 或 VueRequest |
对一个新的 Vue 业务系统,我会优先比较 TanStack Vue Query 与 Pinia Colada,再确定底层使用 ofetch、Ky 还是 Axios。对接口很少的页面,可以从 VueUse 或简单异步函数开始。维护良好的 Axios 项目也可以直接增加合适的数据管理层,底层替换不必成为前置条件。
重试、错误和数据 owner 要明确
成熟 HTTP 客户端与 Query 库都可能有重试。如果外层最多执行 3 次,每一次底层又最多尝试 2 次,一轮查询就可能产生 6 次网络调用。重试应当有明确的负责层,区分网络错误、特定 HTTP 状态、业务失败与用户取消;写操作还要结合幂等契约决定是否允许重试。
错误提示也需要一个出口。请求客户端可以保留 status、业务码、原因与必要上下文,页面再决定使用表单错误、局部重试还是全局提示。每一层都弹 Toast,会让一次最终失败出现多条相同通知。
数据已经由 Query 缓存负责时,通常不再把同一份查询结果同步复制到 Pinia 或 Redux 的另一份状态中。表单编辑草稿可以单独存在,但它与查询结果的关系、保存后如何提交和重新同步,应当是明确的业务流程。
用一组会改变决定的场景试选型
在项目内接入候选后,可以用同一组场景检查行为:
- 两个组件同时订阅相同用户,检查正在进行的查询能否复用,二者是否共享结果。
- 离开页面再回来,分别在新鲜期内、过期但未回收、缓存已回收时检查展示与请求行为。
- 修改资料后,确认详情立即更新,相关活跃列表按规则重新验证,筛选条件与总数仍然正确。
- 快速切换搜索条件,确认旧结果不会覆盖新条件,并检查取消是否实际传到网络请求。
- 切换账号或租户,确认旧缓存、正在进行的请求和后到达的响应不会污染新会话。
- SSR 项目额外确认不同访问者的实例隔离,以及客户端是否复用了服务端传递的数据。
这些场景比单独统计包体积或比较一行 API 更接近维护成本。包体积仍然值得测量,但应基于真实构建和目标入口,不能用 node_modules 的目录大小推导首屏收益。
旧项目迁移时,可以先保留现有接口函数,把需要共享缓存的资源接入 Query 层,再逐步处理取消、错误与失效规则。确实决定更换客户端后,单独验证 JSON、空响应、上传、下载、认证、取消和重试等契约,避免同时改变传输行为与缓存行为后难以定位回归。
数据身份与写后同步
查询 key 决定缓存代表哪份数据,新鲜期和回收期分别控制重新获取与保留。写操作结束后,应按受影响的数据身份失效或更新缓存;HTTP 客户端继续负责一次传输。项目决定采用共享查询模型后,再根据现有框架、SSR 和状态组织选择接入工具。