Learn Apollo 实战:用 dataIdFromObject 与 updateQueries 管理 Apollo Client 缓存

原创2026-10-12 13:35:211,723 阅读
文章标签:教程前端

Learn Apollo 实战:用 dataIdFromObject 与 updateQueries 管理 Apollo Client 缓存

本篇文章基于 Learn Apollo 教程的《Managing Apollo store》扩展阅读(Excursion 02)编写,深入讲解 Apollo Client 在客户端缓存查询与变更(mutation)结果的默认机制、如何通过 dataIdFromObject 实现数据规范化(normalization),以及如何利用 updateQueries 与 immutability-helper 在新增节点后保持 UI 一致性。读完本文,你将掌握 Apollo Client 缓存的核心工作原理,并能在 React 项目中写出“创建节点后列表立即更新”的正确代码。

默认缓存行为:按查询路径缓存数据

在正确配置的前提下,Apollo Client 会自动把查询和 mutation 的结果缓存在客户端 store 中。这意味着不同组件需要同一份数据时,并不会各自保存一份副本,而是统一链接到由 Apollo 管理的同一份缓存数据——这是 Apollo 缓存机制的出发点。

默认情况下,缓存数据是按查询路径(query path)来标识的。在教程的 pokedex 示例中,训练师(Trainer)所拥有的精灵宝可梦节点(ownedPokemons)对应的查询路径为:

RootQuery - Trainer(name: __NAME__) - ownedPokemons

这种按查询路径标识的方式会带来两个典型问题:

  1. 同一条数据可能存在多条查询路径。例如同样一批宝可梦节点,还可以通过服务器上的另一条路径查询到:

    RootQuery - allPokemons

    当两条路径返回相同的节点时,Apollo 无法得知它们其实是同一批数据,缓存中会出现重复副本。

  2. Apollo 默认无法感知 mutation 对数据的影响。例如对某个宝可梦节点执行 updatePokemon mutation 后,mutation 的结果并不会自动合并回已缓存的旧数据,UI 上看到的数据可能依旧是更新前的旧值。

这两个问题正是本文接下来要解决的。

数据规范化:用 dataIdFromObject 归一化缓存

要解决“同数据多路径”的问题,可以在创建 Apollo Client 实例时指定 dataIdFromObject 方法,告诉 Apollo 每个节点应该用什么字段来唯一标识。在 pokedex 场景中,每个节点都有唯一的 id 字段,因此配置如下:

const client = new ApolloClient({
  networkInterface: createNetworkInterface({ uri: 'https://api.graph.cool/simple/v1/__PROJECT_ID__'}),
  dataIdFromObject: o => o.id
})

这里 dataIdFromObject: o => o.id 的含义是:把每个对象的 id 字段映射为它在缓存中的标识。配置完成后,缓存会进入规范化(normalized)状态,查询路径不再作为缓存标识,同一 id 的节点无论通过哪条路径获取,都会落回缓存中的同一位置。

使用该配置时有一个关键前提:必须在每一个查询和 mutation 的结果中显式包含 id 字段。否则 Apollo 无法为节点生成缓存标识,规范化也就无从谈起。

从源码角度看,这一配置在教程中对应 content/tutorial-react-native/react-native-05.md 的 "Data Normalization and the Apollo store" 一节:App.js 中创建 client 时加入 dataIdFromObject,同时 TrainerQuery 中补上 id 字段。教程原文也特别强调:“Unlike Relay, Apollo is not opinionated about if or how objects in query and mutation responses are identified”——Apollo 不像 Relay 那样对节点标识方式有强约定,需要开发者自己通过 dataIdFromObject 声明。

dataIdFromObject 帮我们解决了查询与更新节点时的数据一致性问题,但在创建或删除节点的场景下,还需要多做一步才能让缓存保持一致性。

创建节点时的缓存一致性:从低效回填到 updateQueries

先聚焦创建节点的场景(删除节点的 UI 一致性可以按类似思路处理)。教程中的 createPokemon mutation 最初是这样的:

const createPokemonMutation = gql`
  mutation createPokemon($name: String!, $url: String!, $trainerId: ID) {
    createPokemon(name: $name, url: $url, trainerId: $trainerId) {
      id
    }
  }
`

执行这个 mutation 后,如果不刷新页面,pokedex 列表并不会更新。为什么返回了 id 还不够? 原因在于:Apollo Client 并不知道我们刚刚在 Trainer 查询的 ownedPokemons 这条边上新增了一个节点。它只在 mutation 结果中看到一个全新的 id,于是把新节点加到缓存的根上,却没有信息把它关联到具体的 Trainer 查询,因此 pokedex 无法感知变化。

方案一:在 mutation 结果中带回 trainer 节点

一种直接的做法是让 mutation 结果携带 trainer 节点及其全部 ownedPokemons:

const createPokemonMutation = gql`
  mutation createPokemon($name: String!, $url: String!, $trainerId: ID) {
    createPokemon(name: $name, url: $url, trainerId: $trainerId) {
      trainer {
        id
        ownedPokemons {
          id
        }
      }
    }
  }
`

这段代码的本质是:每次创建新宝可梦时,顺带查询一遍训练师当前拥有的全部宝可梦。Apollo Client 会把 TrainerQuery 返回的 trainer 节点与 mutation 结果中的 trainer 节点按 id 匹配,发现 ownedPokemons 多了一个节点,于是更新 pokedex。

虽然这样能让 UI 保持一致,但效率极低:如果训练师已经拥有几十只宝可梦,每次新建都要重新查询大量已在缓存中的数据,等于让缓存形同虚设。这正是 content/tutorial-react/react-06.md 中评价的 "highly inefficient, this works in our example"。

方案二:updateQueries + immutability-helper

更高效的做法是借鉴 Redux 的 reducer 思想:在指定查询或 mutation 时,通过 updateQueries 定义“本地的 store 应该如何用传入的查询/变更结果进行更新”。

首先引入 immutability-helper 的 update 工具,它可以在不修改既有结构的前提下更新 state:

import update from 'immutability-helper';

在我们的场景中,目标是更新 TrainerQuery 查询对应的缓存片段:

const AddPokemonCardWithMutation = graphql(createPokemonMutation, {
  props({ ownProps, mutate }) {
    return {
      createPokemon({ variables }) {
        return mutate({
          variables: { ...variables },
          updateQueries: {
            TrainerQuery: (prev, { mutationResult }) => {
              const newPokemon = mutationResult.data.createPokemon
              return update(prev, {
                Trainer: {
                  ownedPokemons: {
                    $push: [newPokemon],
                  },
                }
              })
            },
          },
        })
      },
    }
  },
})(withRouter(AddPokemonCard))

这里的关键点:

  • updateQueries 以查询名为键(此处是 TrainerQuery),Apollo 会在 mutation 完成后,用 mutation 结果去执行对应的更新函数。
  • 更新函数签名 (prev, { mutationResult }) 中,prev 是更新前该查询在缓存中的快照,mutationResult.data.createPokemon 是刚刚创建的新节点。
  • 借助 immutability-helper 的 $push 命令,我们把新宝可梦追加到 Trainer.ownedPokemons 数组中,且不破坏原有的不可变数据结构。

这样一来,pokedex 会立即显示新创建的宝可梦,并且不需要重新查询训练师已有的全部数据,缓存的价值得以保留。

从 API 演进看,updateQueries 属于 Apollo Client 1.x 时代的缓存更新机制,后续版本逐步演进为 update 函数与 cache 的 readQuery/writeQuery 组合。本文代码以教程当时的版本为准。

删除节点的缓存一致性:教程中的实际处理

本扩展阅读提到“删除节点的 UI 一致性可以按类似思路处理”,教程正文 content/tutorial-react/react-06.md 给出了具体的坑与解法:

如果把 deletePokemon 的 mutation 结果也改成回填 trainer { id ownedPokemons { id } },由于服务器可能存在字段过滤,Apollo 无法判断返回的是“全部宝可梦 id”还是“子集”,删除操作后缓存中依然保留着已删除的节点。教程采用的快速方案是在 Pokedex 组件的查询选项中开启强制刷新:

const PokedexWithData = graphql(TrainerQuery, {
  options: {
    variables: {
      name: '__NAME__'
    },
    forceFetch: true,
  }
})(Pokedex)

React Native 版本的教程(content/tutorial-react-native/react-native-06.md)则使用了对应的新式写法 fetchPolicy: 'cache-and-network',即“先返回缓存结果,再在网络结果到达后更新”。这两种方式都能换来一致的 UI,代价是牺牲一部分缓存效率——这正好印证了本扩展阅读的主题:在缓存效率与 UI 一致性之间,需要根据业务场景做权衡。

无需规范化也能保持 UI 一致的方案

如果业务场景对“规范化”本身没有强需求,也可以完全不借助规范化来实现一致的 UI。常用的替代手段包括:

  • refetch(重新查询):在 mutation 完成后重新执行相关查询,用服务器最新数据覆盖缓存。
  • polling(轮询):按固定时间间隔自动重新查询,适合数据变动频繁的场景。

另一种需求是:即使缓存里已经有部分数据,也要确保从服务器取回最新结果。此时可以使用 forceFetch 选项(对应 watchQuery 的强制网络请求行为),强制查询绕过缓存直接访问服务器;强制查询返回后,缓存同样会被更新,因此不会破坏缓存的完整性。

仓库源码对照:Relay 与 Apollo 的缓存策略差异

Learn Apollo 站点本身(本仓库)的 mutation 是基于 react-relay 实现的,见 src/mutations/AddPokemonMutation.ts、src/mutations/DeletePokemonMutation.ts 与 src/mutations/UpdatePokemonMutation.ts。从源码结构可以清晰看到两种客户端在“如何声明 store 更新”上的差异:

  • Relay 显式声明:AddPokemonMutation 通过 getFatQuery() 声明 pokemon、edge、viewer { allPokemons } 等可能受影响的字段,再用 getConfigs() 返回 RANGE_ADD 配置(把新节点以 append 行为追加到 allPokemons 连接上);DeletePokemonMutation 用 NODE_DELETE 声明删除;UpdatePokemonMutation 用 FIELDS_CHANGE 声明 pokemon 字段的变更。
  • Apollo 由开发者主导:Apollo Client 本身不强制节点标识方式,需要开发者通过 dataIdFromObject 声明规范化规则,再配合 updateQueries 自行描述“新节点应该被追加到哪里”。这正是本扩展阅读反复强调的“Apollo 需要我们帮它一把”的深层原因。

这一对照也解释了为什么教程(content/tutorial-react/react-05.md)中 createPokemon 需要开发者亲手处理缓存更新,而不是像 Relay 那样由框架通过 fat query 自动推导。

另外,Learn Apollo 站点的内容组织也印证了本扩展阅读在教程中的定位:章节结构定义在 src/utils/content.ts 中,excursions 章节被明确标注为非 Track 的“深入概念”内容(isTrack: false),用于对 Caching with Apollo Client 等主题做 Zoom-in 讲解,是教程正文之外的知识补充。

小结

回顾本扩展阅读的核心结论:

  • 默认缓存按查询路径标识数据,不同路径获取的同一批数据会成为缓存中的独立副本,mutation 也不会自动更新缓存。
  • dataIdFromObject 是规范化缓存的钥匙:把节点映射到唯一 id,并要求所有查询与 mutation 结果包含 id 字段,缓存即可归一化,查询路径不再参与标识。
  • 创建/删除节点需要额外处理:简单方案是在 mutation 结果中回填父级 trainer 节点(低效但可行);高效方案是使用 updateQueries 配合 immutability-helper 的 $push 精确更新 TrainerQuery 的 ownedPokemons。
  • 不追求规范化时,可以通过 refetch、polling 或 forceFetch(新式写法 fetchPolicy: 'cache-and-network')获得一致的 UI,代价是缓存命中率下降。

在实际项目中,建议先评估数据量级与 UI 一致性要求:数据量小、结构简单的应用可以接受 forceFetch 的简单方案;数据量大、跨组件共享频繁的应用则应投入成本做好规范化与 updateQueries 的精细更新,让 Apollo Client 的缓存真正发挥作用。

延伸阅读

  • 官方文档中关于 Apollo Client 工作原理(store 与查询结果的流转)的章节;
  • 官方文档中关于 React 集成下缓存更新(cache updates)的章节;
  • 官方文档中关于轮询与 refetch 的说明,可进一步对比不同 UI 一致性方案的取舍。
登录后查看全文
learnapollo