Learn Apollo 实战:用 dataIdFromObject 与 updateQueries 管理 Apollo Client 缓存
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
这种按查询路径标识的方式会带来两个典型问题:
-
同一条数据可能存在多条查询路径。例如同样一批宝可梦节点,还可以通过服务器上的另一条路径查询到:
RootQuery - allPokemons
当两条路径返回相同的节点时,Apollo 无法得知它们其实是同一批数据,缓存中会出现重复副本。
-
Apollo 默认无法感知 mutation 对数据的影响。例如对某个宝可梦节点执行
updatePokemonmutation 后,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 一致性方案的取舍。