配置 GraphQL 客户端缓存策略

概述

GraphQL 缓存是策略工作，不是全局开关。按字段决定新鲜度，把变更结果写入缓存，并把真正多变的取值留在网络上，让“快”不至于变成“错”。

关键步骤

1. 对很少变化的实体用 cache-first，对期望新鲜的列表用 cache-and-network。
2. 在变更响应中返回被更新的对象，并按 id 写入缓存。
3. 变更后通过显式 update 函数失效或更新受影响的列表字段。
4. 对余额等高波动字段设置 network-only。

验证

• 变更会更新相关实体与列表且无需重新拉取。
• 很少变化的实体由缓存提供。
• 高波动字段始终走网络。
• 长时间会话后缓存规模保持有界。

注意事项

• 缓存策略属于客户端范畴，无法弥补服务端返回不一致数据的问题。
• 滥用 network-only 会抵消缓存，重新引入原本要消除的往返。

适用范围

本条目围绕「配置 GraphQL 客户端缓存策略」给出可复制的步骤、验证方式与常见问题，适合需要按此流程落地的工程团队。执行时请结合自身上下文调整命令与阈值，并在变更前后留存证据，便于后续复核与回滚。

useQuery(GET_USERS, { fetchPolicy: 'cache-and-network' });
useMutation(CREATE_USER, {
  update(cache, { data }) {
    cache.modify({ fields: { users: (prev) => [...prev, data.createUser] } });
  },
});