API 设计 / 系统课时
选择 Fetch Policy 与 Refetch
选择 Fetch Policy 与 Refetch
客户端是否读缓存、何时访问网络,是页面数据语义的一部分。选错策略会导致首屏变慢、旧数据不更新或重复请求;本节用 Apollo Client 说明常用 Fetch Policy,并把主动 refetch 用在明确的刷新场景中。
学习目标
- 根据数据新鲜度和交互目标选择合适的 Fetch Policy
- 区分
cache-first、cache-and-network、network-only与no-cache - 正确使用
refetch主动重新获取当前查询
先按页面语义选策略
cache-first 先查缓存,满足查询就直接返回,缺数据才访问网络,适合详情页回看、稳定字典等允许复用旧结果的场景。cache-and-network 会先给可用缓存,同时继续发网络请求,适合希望快速显示旧值、随后刷新为新值的页面。
network-only 每次都访问网络,响应仍会写入缓存,适合必须以服务器当前结果为准、但仍希望后续查询复用结果的场景。no-cache 同样访问网络,但结果不写入规范化缓存,更适合一次性敏感结果或明确不希望进入共享缓存的数据。cache-only 只读缓存,缓存没有数据时不会自动补网络请求。

用缓存先显再网络刷新
下面示例可作为已安装 React、Apollo Client 与 RxJS 的 Vite React 项目 src/main.tsx。它预先写入“缓存版本”,再用 cache-and-network 先读缓存并并发请求;点击“重新获取”后,refetch 会再次访问网络。
import React from "react";
import { createRoot } from "react-dom/client";
import { ApolloClient, ApolloLink, InMemoryCache, gql } from "@apollo/client";
import { ApolloProvider, useQuery } from "@apollo/client/react";
import { Observable } from "rxjs";
const GET_STATUS = gql`
query GetStatus {
status {
__typename
id
label
}
}
`;
let requestCount = 0;
// 模拟真实网络:每次请求都返回一个更新的服务器版本。
const mockLink = new ApolloLink(() =>
new Observable((observer) => {
const current = ++requestCount;
setTimeout(() => {
observer.next({
data: {
status: {
__typename: "Status",
id: "main",
label: `服务器版本 ${current}`,
},
},
});
observer.complete();
}, 300);
}),
);
const cache = new InMemoryCache();
// 预置旧缓存,用来观察 cache-and-network 的“先缓存、后网络”。
cache.writeQuery({
query: GET_STATUS,
data: {
status: { __typename: "Status", id: "main", label: "缓存版本" },
},
});
const client = new ApolloClient({ cache, link: mockLink });
function StatusPanel() {
// 平时先展示缓存,同时后台请求;refetch 负责用户主动刷新。
const { data, loading, refetch } = useQuery(GET_STATUS, {
fetchPolicy: "cache-and-network",
notifyOnNetworkStatusChange: true,
});
return (
<main>
<p>{data?.status.label ?? "无数据"}</p>
<button disabled={loading} onClick={() => void refetch()}>
{loading ? "获取中…" : "重新获取"}
</button>
</main>
);
}
createRoot(document.getElementById("root")!).render(
<ApolloProvider client={client}>
<StatusPanel />
</ApolloProvider>,
);预期结果
首屏先显示:缓存版本
约 300 ms 后更新为:服务器版本 1
点击“重新获取”后更新为:服务器版本 2实际等待时间会随运行环境变化。示例中的 300 ms 只是模拟网络延迟,不代表真实接口时延。
Refetch 是一次动作,不是长期策略
fetchPolicy 描述查询平时如何在缓存与网络之间取舍;refetch 则是一次明确的重新执行,典型触发点包括用户点击刷新、完成修改后重新确认服务端结果,或页面需要手动恢复最新状态。
不要把“数据可能变化”简单等价为所有查询都使用 network-only。如果页面允许先显示旧值再更新,cache-and-network 往往能减少空白等待;如果数据变化由 mutation 已经精确返回,也可以直接更新缓存,而不是每次修改后都重新拉整页数据。
避免常见策略误用
如果首屏必须新鲜但后续切换页面可以复用缓存,可以结合 nextFetchPolicy:第一次使用网络策略,后续改成 cache-first。若页面需要持续实时更新,则应优先考虑订阅、轮询或明确的事件驱动更新,而不是频繁手工调用 refetch。
选择策略时先回答三个问题:旧数据能否短暂显示、这次网络结果是否应该进入共享缓存、谁负责触发再次获取。围绕这三个问题决策,比按“哪个更快”机械选择 Fetch Policy 更可靠。