Vue Apollo 缓存更新实战:mutation 之后如何让本地缓存与 UI 同步(Cache Updates)

原创2026-10-09 09:54:041,720 阅读
文章标签:前端GraphQL

Vue Apollo 缓存更新实战:mutation 之后如何让本地缓存与 UI 同步(Cache Updates)

在 Vue Apollo(@vue/apollo-composable)应用中,mutation 修改了服务端数据后,本地 Apollo 归一化缓存必须同步更新,UI 才能随之刷新。Apollo Client 能自动处理一部分场景(如更新已有实体),但插入新实体、删除实体、以及列表类查询的联动变化都需要开发者显式编排。本文以 cache-updates.md 为骨架,系统讲解三种缓存同步模式(refetchQueries 重取查询、update 函数直接写缓存、字段策略 merge),并结合仓库源码(useMutation.ts)剖析每个选项的底层行为,帮助你写出即时、正确且可维护的 mutation 缓存更新代码。

何时缓存会自动更新:什么都不用做

如果 mutation 返回了被修改的完整实体(包含 __typename 和主键字段),Apollo Client 会把它自动合并进归一化缓存。所有读取该实体的 useQuery 都会以新值重新触发渲染,无需任何额外接线:

import { useMutation } from '@vue/apollo-composable'

const { mutate } = useMutation(gql`
  mutation UpdateTodo($id: ID!, $completed: Boolean!) {
    updateTodo(id: $id, completed: $completed) {
      id
      text
      completed
    }
  }
`)

运行这个 mutation 之后,任何读取 Todo:<id> 的 useQuery 都会自动更新。这覆盖了大多数"编辑已有实体"的场景,是成本最低的方案。

缓存无法推断的三种情况

归一化缓存只负责按实体 id 合并字段,它无法推断:

  1. 新建的实体应该出现在某个已存在的列表里(例如 createTodo 返回的新 Todo 应加入 todos 查询结果);
  2. 被删除的实体应该从列表中消失;
  3. 相关查询的结果应作为副作用发生变化。

遇到这三类情况,就需要下面的模式之一。

从源码结构看,上述行为完全由 @apollo/client 的 InMemoryCache 归一化机制驱动,Vue Apollo 的职责是把 client.mutate 的选项原样传递下去。在 useMutation.ts 中,mergedOptions 将 refetchQueries、update、onQueryUpdated、awaitRefetchQueries 等缓存类选项与 mutation 文档一起展开后交给 client.mutate。

Pattern 1:用 refetchQueries 重取查询

最直接的列表更新方式:告诉 Apollo 在 mutation 完成后重新执行哪些查询。

import { useMutation } from '@vue/apollo-composable'

const CREATE_TODO = gql`
  mutation CreateTodo($text: String!) {
    createTodo(text: $text) {
      id
    }
  }
`

const GET_TODOS = gql`
  query GetTodos {
    todos {
      id
    }
  }
`

const { mutate } = useMutation(CREATE_TODO, {
  refetchQueries: [
    GET_TODOS,
    'GetTodos',
  ],
})

refetchQueries 数组中的每一项要么是一个 DocumentNode(按文档重取),要么是一个查询名字符串(按 operation name 重取)。根据 useMutation.ts 的类型定义,还支持以下形式:

  • { query, variables } 对象:重取时携带指定变量,如 { query: GET_TODOS, variables: { userId: '1' } };
  • 'active':重取应用中所有活跃查询。所谓活跃查询是指至少有一个订阅者(挂载中的组件或存活的 composable)的查询;
  • 'all':重取所有查询,包括活跃和不活跃(已被缓存但无活跃订阅者)的查询。多数情况下应使用 'active' 而非 'all',详见 refetching.md;
  • 函数 (result) => [...]:根据 mutation 返回结果动态决定要重取的查询,例如只在特定字段变化时才重取。

何时选用该模式

  • mutation 影响了多个互不相关、难以逐一枚举的查询;
  • 你希望即使 update 逻辑写错,结果也一定正确(以服务端为准);
  • 可以接受额外的网络往返。

缺点:每列出一个查询就会发起一次服务端请求,即使仅靠 mutation 返回值就能完成缓存更新。

等待重取完成:awaitRefetchQueries

默认情况下 mutate() 在 mutation 完成时立即 resolve,重取在后台并行进行。若希望 mutate() 等所有重取全部结束后再 resolve,设置 awaitRefetchQueries: true:

const { mutate } = useMutation(CREATE_TODO, {
  refetchQueries: [GET_TODOS],
  awaitRefetchQueries: true,
})

该选项默认值为 false(见 useMutation.ts 的类型注释),需要"重取完成后立即读取最新结果"的场景(如重取后立刻跳转详情页)才需要开启。

关于重取家族的更多对比(单查询 refetch()、轮询 pollInterval、应用级 client.refetchQueries),参见 Refetching。

Pattern 2:用 update 函数直接写缓存

如果希望在不额外发网络请求的情况下保持 UI 同步,可以在 update 回调中直接修改缓存。update 接收 cache 和 mutation 结果两个参数:读取出需要的数据、构造新状态、写回缓存;Apollo Client 随后会把变更广播给所有读取受影响实体的活跃查询,UI 立即更新:

import { useMutation } from '@vue/apollo-composable'

const CREATE_TODO = gql`
  mutation CreateTodo($text: String!) {
    createTodo(text: $text) {
      id
      text
      completed
      __typename
    }
  }
`

const GET_TODOS = gql`
  query GetTodos {
    todos {
      id
      text
    }
  }
`

const { mutate } = useMutation(CREATE_TODO, {
  update(cache, { data }) {
    if (!data?.createTodo)
      return

    const existing = cache.readQuery({ query: GET_TODOS })
    if (!existing)
      return

    cache.writeQuery({
      query: GET_TODOS,
      data: {
        todos: [...existing.todos, data.createTodo],
      },
    })
  },
})

几点实操注意:

  • update 的类型签名是 (cache: ApolloCache, result: { data?: object }) => void(见 useMutation.ts),第一参数就是与 client.cache 同一个 ApolloCache 实例;
  • readQuery 只针对缓存执行 GraphQL 查询,不会发起网络请求;缓存中缺少任一请求字段时返回 null,所以要先做空值守卫;
  • 不要修改 readQuery 返回的对象——同一引用可能被多个组件共享,应视为只读数据,安全更新请用 writeQuery 或 cache.modify(详见 interaction.md)。

用 cache.modify 做外科手术式更新

cache.modify 往往是更简洁的替代方案:无需读出并重写整个查询,只声明字段级的变化规则。以"插入列表"为例:

import { gql, useMutation } from '@apollo/client'

const { mutate } = useMutation(CREATE_TODO, {
  update(cache, { data }) {
    if (!data?.createTodo)
      return

    cache.modify({
      fields: {
        todos(existingRefs = [], { readField }) {
          const newRef = cache.writeFragment({
            data: data.createTodo,
            fragment: gql`
              fragment NewTodo on Todo {
                id
                text
                completed
              }
            `,
          })

          // 乐观响应可能让该回调执行两次,需去重
          if (existingRefs.some((ref: any) => readField('id', ref) === data.createTodo.id)) {
            return existingRefs
          }

          return [...existingRefs, newRef]
        },
      },
    })
  },
})

这里 writeFragment 先把新实体写入归一化缓存并返回其引用(reference),readField('id', ref) 则在不展开引用的情况下读取其 id 字段用于去重。由于乐观响应与真实响应都会触发 update 回调,必须用"已存在则原样返回"的守卫防止重复插入。

从列表中移除一项,则对引用数组做过滤:

cache.modify({
  fields: {
    todos(existingRefs = [], { readField }) {
      return existingRefs.filter(
        (ref: any) => readField('id', ref) !== deletedId,
      )
    },
  },
})

彻底驱逐整个实体,使用 evict + gc:

cache.evict({ id: cache.identify({ __typename: 'Todo', id: deletedId }) })
cache.gc()
  • cache.identify({ __typename: 'Todo', id: deletedId }) 返回形如 'Todo:5' 的缓存 ID;用 identify 构造 ID 是安全做法,因为它会尊重你在 typePolicies 中配置的 keyFields;
  • evict 让缓存遗忘该实体,任何包含该实体引用的列表在下次读取时会自动将其剔除;
  • gc()(垃圾回收)清理不再被任何根字段引用的孤立对象,防止内存膨胀(完整 API 见 interaction.md)。

何时选用该模式

  • 你能精确描述缓存变更(指定位置插入、按 id 删除、替换某字段);
  • 希望 UI 立即更新,不需要服务端往返;
  • 能接受错误缓存更新带来的短暂脏数据风险,或用下文"更新后重取(refetch after update)"兜底。

Pattern 3:字段策略(merge)

对于总是以相同方式合并的数据(典型如分页列表),与其在每个 mutation 里写 update 回调,不如在缓存配置里为字段定义 merge 函数:

import { InMemoryCache } from '@apollo/client'
import { offsetLimitPagination } from '@apollo/client/utilities'

const cache = new InMemoryCache({
  typePolicies: {
    Query: {
      fields: {
        feed: offsetLimitPagination(), // 内置的 offset/limit 合并助手
      },
    },
  },
})

merge 决定新一页数据如何与已缓存内容合并(追加、去重或按游标拼接)。Apollo 为 offset 分页与游标分页提供了内置助手,自定义需求可以手写 merge。分页场景下,列表的插入/删除通常配合 update 回调或 refetchQueries 完成,详见 Pagination Overview。

组合使用多种模式

实践中常常叠加使用:

  • 乐观响应 + update:optimisticResponse 会把预测结果先喂给同一个 update 回调,UI 瞬时更新;服务端返回真实结果后 update 再次执行并收敛为真实数据。注意回调会执行两次,update 逻辑必须幂等(参考上文去重守卫)。完整生命周期见 Optimistic UI;
  • update + 更新后重取:先用缓存直写获得即时反馈,再通过重取校验以纠正任何偏差(见下一节)。

更新后重取(Refetch after update):安全网

如果 update 函数可能写得不完全正确,可以借助 onQueryUpdated 让 Apollo 对 mutation 影响的每个查询执行重取,作为校验步骤:

const { mutate } = useMutation(CREATE_TODO, {
  update(cache, { data }) {
    // ...你的缓存更新逻辑
  },
  onQueryUpdated(observableQuery) {
    return observableQuery.refetch()
  },
})

onQueryUpdated 会针对每个受缓存变更影响的活跃查询调用一次,返回值决定后续行为(见 useMutation.ts 的类型定义):

  • 返回 false:跳过该查询,不重取;
  • 返回 true:保留查询现状,不重取;
  • 返回 Promise(典型为 observableQuery.refetch()):等待该重取完成,mutate() 会 await 这个 Promise。

它的定位是"安全网":乐观缓存更新提供即时反馈,重取在片刻之后纠正任何不准确之处。与 refetchQueries 的联动、以及用 onQueryUpdated 过滤无关查询(如按 queryName 跳过)的写法,参见 refetching.md。

从 mutation 外部更新缓存

缓存更新不只发生在 mutation 里。WebSocket 推送事件、定时轮询结果、登录后的状态恢复等场景同样需要写缓存。此时通过 useApolloClient 拿到 client,直接操作 client.cache:

import { useApolloClient } from '@vue/apollo-composable'

const { client } = useApolloClient()

client.cache.modify({
  fields: {
    todos(existingRefs = [], { readField }) {
      // ...
    },
  },
})

任何读取被修改字段的 useQuery 都会自动更新。从源码看(useApolloClient.ts),useApolloClient 返回的 client 是一个 getter:在组件 setup 中优先通过 DefaultApolloClient / ApolloClients 注入解析,组件外部则回退到 provideApolloClient / provideApolloClients 设置的模块级状态;解析不到客户端时会抛出包含排查提示的错误(提示在组件外使用 app.runWithContext() 或 provideApolloClient())。若应用配置了多个命名客户端,也可用 useApolloClient('clientId') 或 resolveClient('clientId') 获取指定实例。

下一步

  • Optimistic UI:让 mutation 在等待服务端时也"感觉即时",并了解乐观值回滚机制;
  • Reading & Writing the Cache:覆盖 readQuery / readFragment / writeQuery / writeFragment / modify / evict 等全部缓存读写方法;
  • Refetching:对比 refetch()、pollInterval、refetchQueries、client.refetchQueries 等重取模式的适用场景;
  • Mutations:useMutation 的基础用法、响应式变量与事件钩子;
  • useMutation 类型参考:查看本文所有选项(refetchQueries、awaitRefetchQueries、update、onQueryUpdated、optimisticResponse、fetchPolicy、keepRootFields 等)的完整类型定义与默认值。
登录后查看全文
apollo