Vue Apollo 缓存读写实战:在 @vue/apollo-composable 中直接操作 Apollo Client Cache
Vue Apollo 缓存读写实战:在 @vue/apollo-composable 中直接操作 Apollo Client Cache
在 Vue 应用中,很多场景需要绕过网络层直接与 Apollo Client 的规范化缓存(normalized cache)交互——例如在 mutation 的 update 回调中同步列表、维护 local-only 字段、或在工具函数、状态管理 store 中读取缓存数据。本文以 packages/docs/caching/interaction.md 为主线,系统讲解在 Vue Apollo(@vue/apollo-composable)上下文中如何拿到缓存实例、使用 readQuery / readFragment 读取、writeQuery / writeFragment 写入、cache.modify 做外科手术式更新,以及 evict / gc / clearStore 的清理策略。读完你将对 Apollo 缓存 API 在 Vue 组合式 API 下的完整调用方式与底层机制有清晰认知,可直接应用于真实项目。
访问缓存的两种典型上下文
Apollo Client 的所有缓存方法(readQuery、writeQuery、modify、identify 等)都挂在 ApolloCache 实例上。在 Vue Apollo 中,获取这个实例主要有两条路径,二者拿到的是同一个 ApolloCache 实例,后续所有方法在两个上下文中的用法完全一致。
场景一:mutation 的 update 回调内部
Apollo Client 会把缓存实例作为 update 回调的第一个参数传入,这是最常用的缓存写入入口:
import { TypedDocumentNode } from '@apollo/client'
import { useMutation } from '@vue/apollo-composable'
const CREATE_TODO: TypedDocumentNode<{ createTodo: { id: string, text: string } }, { text: string }> = gql``
useMutation(CREATE_TODO, {
update(cache, { data }) {
// `cache` 即 ApolloCache 实例
},
})
从源码看,useMutation 会把 update 等选项原样合并进传给 client.mutate 的选项中(见 useMutation.ts),因此回调签名与原生 Apollo Client 完全一致:update(cache, result)。result 中可解构出 data(以及 errors 等),配合 cache.readQuery / cache.writeQuery / cache.modify 即可在 mutation 完成后精确同步本地缓存,避免额外的网络请求。该 update 回调在乐观响应与真实响应到达时各触发一次,编写时需保证逻辑幂等(详见下文去重示例)。
场景二:通过 useApolloClient 在任意位置获取
对于组件 setup 之外的场景(事件处理器、Pinia store、路由守卫、工具函数),使用 useApolloClient 组合式函数取回客户端实例:
import { useApolloClient } from '@vue/apollo-composable'
const { client } = useApolloClient()
// client.cache 与 update 回调中的 cache 是同一个 ApolloCache 实例
client.cache.readQuery({ /* ... */ })
useApolloClient 的解析策略从源码中可见(useApolloClient.ts):在组件 setup 的注入上下文中,优先通过 inject(ApolloClients, null) 与 inject(DefaultApolloClient, null) 解析客户端;若不存在注入上下文(如在普通函数中调用),则回退到模块级状态。它返回 { resolveClient, client },其中 client 是一个 getter,在客户端无法解析时会抛出明确错误,提示使用 app.runWithContext() 或 provideApolloClient()(见 useApolloClient.ts)。多客户端场景下还可传入 clientId 获取命名客户端:useApolloClient('analytics')。
读取缓存:readQuery 与 readFragment
读取操作不会发起网络请求,完全基于本地规范化缓存。
readQuery:按查询读取
readQuery 接收一个 GraphQL 查询文档与变量,返回与查询结构一致的结果对象。若缓存中缺少任何一个被请求的字段,则返回 null,而不是抛错或部分返回:
const READ_TODO = gql`
query ReadTodo($id: ID!) {
todo(id: $id) {
id
text
completed
}
}
`
const result = cache.readQuery({
query: READ_TODO,
variables: { id: '5' },
})
// 若 READ_TODO 是 TypedDocumentNode,result?.todo 具备完整类型推导
使用要点:
- 完全从缓存读取,绝不访问网络;
- 字段缺失即返回
null,适合在写入前做存在性判断; - 若使用
TypedDocumentNode类型的查询文档,返回结果可享受完整的 TypeScript 类型提示。
::: warning 不要修改返回的对象
readQuery 返回的对象引用可能被多个组件共享,请将其视为不可变数据。安全地更新缓存应使用 writeQuery 或 cache.modify,而不是直接改返回对象。
:::
readFragment:按缓存 ID 读取单个实体
当只需要读取某个特定实体的部分字段、不想为它单独编写完整查询时,readFragment 更轻量:
const TODO_FIELDS = gql`
fragment TodoFields on Todo {
id
text
completed
}
`
const todo = cache.readFragment({
id: 'Todo:5',
fragment: TODO_FIELDS,
})
其中 id: 'Todo:5' 是实体的缓存 ID。推荐用 cache.identify(见下文"识别实体"一节)从实体对象生成缓存 ID,而不是手写拼接字符串,这样能自动尊重 typePolicies 中配置的 keyFields。
写入缓存:writeQuery 与 writeFragment
writeQuery:按查询形状写入
writeQuery 将数据以查询结果的结构写入缓存。它创建或合并到已存在的缓存实体中,data 中未提及的既有字段会被保留:
cache.writeQuery({
query: READ_TODO,
variables: { id: '5' },
data: {
todo: {
__typename: 'Todo',
id: '5',
text: 'Buy grapes',
completed: false,
},
},
})
注意 data 中必须包含 __typename 与关键字段(key field),缓存才能据此定位实体。写入完成后,所有读取了该实体的活跃查询会自动重新触发渲染。
writeFragment:按缓存 ID 写入单个实体
与 readFragment 对应的写操作:
cache.writeFragment({
id: 'Todo:5',
fragment: TODO_FIELDS,
data: {
__typename: 'Todo',
id: '5',
text: 'Updated text',
completed: true,
},
})
writeFragment 的返回值是一个指向该实体的引用(Reference),这个返回值在配合 cache.modify 向列表插入新实体时非常有用(见下文)。
外科手术式更新:cache.modify
对于"改一个字段、往列表插入一条、从列表移除一条"这类精细操作,cache.modify 可以避免读取并重写整个查询,只针对目标字段做局部修改:
cache.modify({
id: cache.identify({ __typename: 'Todo', id: '5' }),
fields: {
completed(current) {
return !current
},
},
})
cache.modify 的 fields 中每个函数接收该字段的当前值(对引用类型字段收到的是引用数组),返回新值即可。此外还有两个特殊返回值,均从 @apollo/client/cache 导入:
DELETE:删除该字段;INVALIDATE:将该字段标记为"脏",使依赖它的查询触发重新拉取(refetch)。
向列表插入新实体
插入列表的典型套路:先用 writeFragment 把新实体写入缓存并获得其引用,再将该引用追加到列表字段的引用数组中:
import { gql } from '@apollo/client'
cache.modify({
fields: {
todos(existingRefs = [], { readField }) {
const newTodoRef = cache.writeFragment({
data: newTodo,
fragment: gql`
fragment NewTodo on Todo {
id
text
completed
}
`,
})
// 避免重复插入(乐观响应可能导致本回调触发两次)
if (existingRefs.some(ref => readField('id', ref) === newTodo.id)) {
return existingRefs
}
return [...existingRefs, newTodoRef]
},
},
})
这里有两个值得注意的细节:
fields回调的第二个参数解构出readField,用于从引用(Reference)中读取字段值做比较/筛选;- 由于乐观响应和真实响应都会执行一次
update回调,插入前必须用readField('id', ref) === newTodo.id做去重判断,防止同一实体被插入两次。完整的 mutation-update 模式见 cache-updates.md。
从列表移除实体
利用 readField 过滤掉目标引用即可:
cache.modify({
fields: {
todos(existingRefs = [], { readField }) {
return existingRefs.filter(
ref => readField('id', ref) !== deletedId,
)
},
},
})
配合 cache.evict 可以整体移除实体(见下文"删除与失效"一节)。
识别实体:cache.identify
cache.identify 根据对象返回其规范化缓存 ID:
const cacheId = cache.identify({ __typename: 'Todo', id: '5' })
// 'Todo:5'
这是构造缓存 ID 的安全方式:它自动尊重你在 InMemoryCache 的 typePolicies 中配置的 keyFields(例如用 slug 代替 id 作为关键字段的实体,identify 也会返回正确的 ID),避免手写 'Todo:5' 这类硬编码字符串带来的隐患。在 useFragment.ts 的 resolveFromToId 实现中可以看到,useFragment 组合式函数在解析 from 参数时正是通过 cache.identify(from) 来获得缓存 ID 的——这印证了 identify 是框架内部也依赖的标准入口。
在组件之外监听缓存变化
useQuery 组合式函数内部会自动订阅缓存变化(底层通过 client.watchQuery 建立观察,见 useQuery.ts)。如果你需要在组件 setup 之外获得同样的监听能力——比如在 worker、store action、事件监听器中——可以绕过组合式函数,直接使用 client.watchQuery:
import { useApolloClient } from '@vue/apollo-composable'
const { client } = useApolloClient()
const observable = client.watchQuery({
query: GET_TODOS,
variables: { userId: '1' },
})
const subscription = observable.subscribe((next) => {
console.log('Todos changed:', next.data)
})
// 不再需要时务必清理
subscription.unsubscribe()
observable.stop()
要点:
watchQuery返回一个 ObservableQuery,通过subscribe持续收到数据更新;- 手动建立的订阅不会随组件销毁自动清理,必须在合适时机调用
subscription.unsubscribe()与observable.stop(),否则会内存泄漏。
片段级别的组件外监听,等价物是 client.watchFragment;在组件内部则优先使用 useFragment 组合式函数(其底层正是对 client.watchFragment 的封装,并额外提供 current、result、complete、missing 等响应式 ref,见 useFragment.ts)。组件外一次性读取片段数据可直接调用 client.readFragment。
删除与失效:evict、gc、clearStore
cache.evict + cache.gc:清除实体并回收垃圾
cache.evict 从缓存中移除一个实体(或某个字段),通常与 cache.gc() 配对使用,回收不再被任何查询引用的孤立对象:
cache.evict({ id: 'Todo:5' })
cache.gc()
注意执行顺序:evict 先解除实体与查询之间的引用关系,gc 再清扫完全不可达的对象。列表中对被逐出实体的引用会在下次读取时自动消失。
client.clearStore / client.resetStore:全局清空
登出等需要"清空一切"的场景,client.clearStore() 会移除全部缓存数据且不通知活跃查询:
await client.clearStore()
若希望清空后活跃查询重新拉取数据,改用 client.resetStore() 即可——它会清空缓存并主动触发活跃查询的重新请求,适合登录态切换后刷新页面数据的需求。
小结与下一步
本文覆盖了 Vue Apollo 缓存交互的完整 API 面:
| API | 用途 |
|---|---|
cache.readQuery |
按查询读取,缺字段返回 null |
cache.readFragment |
按缓存 ID 读取单实体 |
cache.writeQuery / writeFragment |
按查询 / 按 ID 写入或合并 |
cache.modify |
外科手术式局部修改,支持 DELETE / INVALIDATE |
cache.identify |
依据 typePolicies.keyFields 生成缓存 ID |
client.watchQuery / watchFragment |
组件外监听缓存变化 |
cache.evict / gc |
逐出实体并回收垃圾 |
client.clearStore / resetStore |
全局清空 / 清空并重拉 |
无论通过 mutation 的 update 回调还是 useApolloClient 拿到缓存,读取与写入 API 的行为完全一致,这也是本文中示例把二者混用的原因。你可以继续深入以下仓库内文档:
- cache-updates.md:mutation 后同步缓存的完整模式(refetch、update、field policy 的组合);
- optimistic-ui.md:利用缓存写入实现乐观 UI 即时反馈;
- outside-components.md:在路由守卫、独立脚本等组件外场景安全使用组合式函数;
- fragments.md:组件内使用
useFragment的完整指南。