API 设计 / 系统课时
更新 Mutation 后的客户端缓存
更新 Mutation 后的客户端缓存
Mutation 成功只代表服务端数据已改变,界面是否同步还取决于缓存。本文用 Apollo Client 4 演示返回实体、cache.modify 与 optimisticResponse 的配合,让列表在请求前后都保持一致。
学习目标
- 判断哪些字段会因规范化写入自动更新,哪些列表关系需要手动维护
- 使用
update、cache.modify和writeFragment安全更新缓存引用 - 为 Mutation 配置可回滚的乐观结果,避免等待网络后才刷新界面
先区分实体更新与列表更新
Apollo Client 的 InMemoryCache 会按实体标识规范化数据。若 addTask 返回 __typename、id、title、completed,真实响应到达后,缓存可以创建或覆盖对应的 Task:<id>。因此,“修改已有实体的字段”通常不需要把整个查询重写一遍。
但新实体进入规范化缓存,不等于它会自动出现在 Query.tasks 列表里。列表保存的是实体引用,Apollo Client 不知道新任务应该插在开头、末尾还是某个筛选结果中,这部分业务关系要由字段策略、update 或重新查询明确表达。

用一个 Mutation 完成一致更新
下面假设页面已经由 ApolloProvider 提供客户端,Query.tasks 不带参数,服务端的 addTask(title) 返回新增任务。示例同时查询列表并执行 Mutation,让缓存变化可以直接反映到页面。
import { gql } from "@apollo/client";
import { useMutation, useQuery } from "@apollo/client/react";
const TASKS = gql`
query Tasks {
tasks {
__typename
id
title
completed
}
}
`;
const ADD_TASK = gql`
mutation AddTask($title: String!) {
addTask(title: $title) {
__typename
id
title
completed
}
}
`;
const NEW_TASK_FRAGMENT = gql`
fragment NewTask on Task {
__typename
id
title
completed
}
`;
export function TaskPanel() {
const { data } = useQuery(TASKS);
const [addTask, { loading }] = useMutation(ADD_TASK, {
update(cache, { data: mutationData }) {
const task = mutationData?.addTask;
if (!task) return;
// 先得到规范化 Task 的 Reference,再修改无参数的 Query.tasks 列表。
const newTaskRef = cache.writeFragment({
data: task,
fragment: NEW_TASK_FRAGMENT,
});
cache.modify({
fields: {
tasks(existingRefs = [], { readField }) {
const exists = existingRefs.some(
(ref) => readField("id", ref) === task.id,
);
return exists ? existingRefs : [newTaskRef, ...existingRefs];
},
},
});
},
});
async function handleAdd() {
const title = "检查缓存一致性";
const optimisticId = `optimistic:${crypto.randomUUID()}`;
await addTask({
variables: { title },
optimisticResponse: {
addTask: {
__typename: "Task",
id: optimisticId,
title,
completed: false,
},
},
});
}
return (
<section>
<button type="button" disabled={loading} onClick={handleAdd}>
添加任务
</button>
<ul>
{data?.tasks.map((task) => (
<li key={task.id}>{task.title}</li>
))}
</ul>
</section>
);
}预期结果
点击按钮后:任务“检查缓存一致性”立即出现在列表首部。
请求成功后:乐观层被移除,列表保留服务端返回的真实 Task。
请求失败时:乐观层被回滚,临时任务从列表中消失。当配置了 optimisticResponse 时,update 会先基于乐观结果执行一次,真实响应到达后再执行一次。示例中的去重判断因此很重要:缓存更新逻辑应当允许重复调用,而不是假定它只发生一次。
设计可靠的乐观结果
乐观对象必须与 Mutation 的返回结构兼容,尤其要提供稳定的 __typename 和临时 id,这样缓存才能把它当作一个可引用实体。临时 ID 不应与服务端真实 ID 冲突;真实响应到达后,Apollo Client 会移除乐观层,再根据真实结果更新基础缓存。
若 Mutation 只是修改一个已经缓存的 Task,并且响应返回该实体的 id 与被修改字段,通常依靠规范化写入即可。如果 Mutation 改变了列表成员关系、排序、聚合计数或跨实体关联,再使用 cache.modify 或字段策略补齐关系。若 tasks 带筛选参数,还要按参数判断应修改哪个列表,不能把新实体无条件插入所有缓存变体。
什么时候改缓存,什么时候重新查询
直接改缓存适合客户端能准确推导结果的场景,例如新增项插到列表首部、删除已知 ID、切换布尔状态。它避免额外网络请求,界面也能更快稳定下来。
如果服务端还会执行客户端无法重现的排序、权限过滤、推荐计算或多实体副作用,优先让 Mutation 返回足够信息;仍无法确定时使用 refetchQueries 获取权威结果。缓存更新的目标不是“少请求”,而是在不猜测服务端状态的前提下,让本地视图与真实数据保持一致。