urql Graphcache 缓存更新(Cache Updates)完全指南:Mutation/Subscription 手动维护、失效与乐观更新
urql Graphcache 缓存更新(Cache Updates)完全指南:Mutation/Subscription 手动维护、失效与乐观更新
在 urql 的 Graphcache 规范化缓存中,查询结果会以实体为节点、链接为边被自动写入缓存;但当 mutation 或 subscription 返回的数据粒度不足以覆盖所有受影响的实体(例如列表新增、删除、字段排序变化)时,就需要通过 updates 配置编写"更新器(updater)"来手动维护缓存中的链接与记录。本文基于 docs/graphcache/cache-updates.md 展开,结合 exchanges/graphcache 的源码实现,系统讲解 cache.writeFragment、cache.updateQuery、cache.link、cache.inspectFields、cache.invalidate 与乐观更新(optimistic)的完整用法。读完本文你将掌握:如何判断一个 mutation 是否需要更新器、如何用四种 cache 方法维护实体与列表、如何精准失效单个字段或整个类型,以及如何用乐观更新让应用瞬间响应。
从规范化缓存说起:为什么 mutation 结果不能总是自动更新一切
要理解 Cache Updates 的价值,需要先回顾 Graphcache 的存储模型(详见 规范化缓存):当 Graphcache 收到 API 结果时,它会遍历结果并将所有数据以规范化结构存入缓存——每个可键控(keyable)的实体都按其实体键(如 Todo:1)存储;查询结果是一张从根实体 Query 出发的图,也可理解为树:Query 通过**链接(link)连接到其他实体(链接本质上是存储的实体键),每个实体内部又用记录(record)**保存标量值,即树的叶子。
正如 规范化缓存 中所述:
任何 mutation 或 subscription 也可以被写入这个数据结构。一旦 Graphcache 在其结果中发现可键控实体,就会把它写入关系表,这可能更新应用中其他查询。
也就是说,mutation 和 subscription 的结果同样会被写入并更新缓存中的实体,这些更新会自动反映到应用所有活跃查询上。但这种方式有局限:resolver 可以被动地改变查询数据的形态(详见 本地 Resolver),而 mutation 和 subscription 往往无法被动计算数据——当它们返回的结果比缓存更新所有受影响实体所需的信息更"碎片化"时,我们就必须编写 updater(更新器) 来主动更新链接与关系。
updates 配置与 updater 的四个参数
cacheExchange 的 updates 选项接收一个映射,键为 Mutation 或 Subscription,值为各字段对应的"更新函数"。这些函数与 本地 Resolver 以及 GraphQL.js 服务端 resolver 的形态类似:
cacheExchange({
updates: {
Mutation: {
mutationField: (result, args, cache, info) => {
// ...
},
},
Subscription: {
subscriptionField: (result, args, cache, info) => {
// ...
},
},
},
});
在 exchanges/graphcache/src/types.ts 中,UpdateResolver 的类型签名确认了这一结构——它接收四个位置参数并返回 void:
result(对应类型定义中的parent):正在被写入缓存的完整 API 结果。通常我们应避免耦合,只关注 updater 所挂载字段的数据,但值得注意的是你可以访问结果的任何部分。args:该字段被调用时携带的参数;若字段未携带参数,则被替换为空对象{}。cache:cache实例,提供读写本地缓存的方法,其完整 API 见 API 文档。本文后面会频繁使用它来读写缓存。info:不应频繁使用,但它包含查询文档遍历的运行时信息(如variables、parent、parentKey等),可用于让 resolver/updater 可复用或获取整个查询的信息,完整 API 见 API 文档。
由于 updater 的返回值被忽略(TypeScript 中类型为 void),它们对 cache 实例的所有调用都是副作用——这些副作用可能触发额外的缓存变更,并在修改的同时更新所有受影响查询。从源码 exchanges/graphcache/src/operations/write.ts 可以看到,updater 是在字段被正常写入缓存之后才执行的("We run side-effect updates after the default, normalized updates so that the data is already available in-store if necessary"),此时被更新的数据已经就位,updater 可以直接读取。
Graphcache v7 起的默认 mutation 失效行为
从 Graphcache v7 开始(见 exchanges/graphcache/CHANGELOG.md),没有配置 updates.Mutation.<fieldName> 更新器的 mutation 拥有一套回退行为:
- 如果 mutation 返回了一个在缓存中尚找不到的实体,Graphcache 将其视为一次"创建(create)"mutation;
- Graphcache 随后会失效(invalidate)与该返回实体
__typename相同的所有已缓存实体,从而触发相关查询重新请求。
只要为该 mutation 字段定义了 updater,这套回退行为就不再运行,你的 updater 将完全接管 mutation 写入之后的处理。
这段回退逻辑在源码中清晰可见:exchanges/graphcache/src/operations/write.ts 中的 else if (typename === ctx.store.rootFields['mutation'] && !ctx.optimistic) 分支会检查 mutation 返回的字段值:若为对象或数组,则通过 store.keyOfEntity 计算其实体键,再用 readRecord(key, '__typename') 与 getRefCount(key) 判断该实体是否已存在于缓存;若"没有已解析的 __typename 或引用计数为 0",就调用 invalidateType(fieldValue.__typename, ...) 失效该类型下的其他实体。
什么时候才需要编写缓存更新器?
设计良好的 GraphQL schema 通常不需要编写太多缓存更新器。例如,一个更新 User 用户名的 mutation,如果它也查询并返回了 User 实体,就能平凡地自动更新缓存:
query User($id: ID!) {
user(id: $id) {
__typename # "User"
id
username
}
}
mutation UpdateUsername($id: ID!, $username: String!) {
updateUser(id: $id, username: $username) {
__typename # "User"
id
username
}
}
上例中,Query.user 返回 User,Mutation.updateUser 也查询并返回同一个 User,因此更新后的用户名会被 Graphcache 自动应用。如果 mutation 字段不返回 User,这一自动更新就不可能发生——虽然仍可为它编写 updater,但这通常意味着 schema 设计不佳。
updater 真正变得不可或缺的场景是:mutation 无法合理地返回已变更的内容,或我们无法手动定义一个能选出所有可能变更字段的选择集。常见例子:
Mutation.deleteUser:需要失效一个实体;Mutation.createUser:某个列表现在可能需要包含新实体;Mutation.createBook:某个既有实体(如User.books字段)的链接需要更新。
简而言之,**任何我们无法通过 mutation 直接查询到的关系(链接)**都可能需要编写缓存更新器——因为这些数据变更 Graphcache 无法自行看到并存储。后文 cache.link 小节 会说明:cache.link 用于把字段指向不同的实体(即把一个实体字段的关系更新到另一个或一组子实体),这是最常见的更新需求,优先尝试使用 cache.link,除非你需要更新的是标量。
手动更新实体:cache.writeFragment
如果 mutation 字段的结果没有返回它要更新的完整实体,Graphcache 就无法自动更新该实体。例如:
mutation UpdateTodo($todoId: ID!, $date: String!) {
updateTodoDate(id: $todoId, date: $date)
}
这里 Mutation.updateDate 解析为一个标量而非完整的 Todo 对象类型。修复方式之一是修改 API schema,让该 mutation 返回完整的 Todo 实体,这样 mutation 就能写成下面这样,并让 Todo 在缓存中自动更新:
mutation UpdateTodo($todoId: ID!, $date: String!) {
updateTodoDate(id: $todoId, date: $date) {
...Todo_date
}
}
fragment Todo_date on Todo {
id
updatedAt
}
如果无法修改 schema,则可以编写 updater,通过 cache.writeFragment 手动更新 Todo 实体:
import { gql } from '@urql/core';
cacheExchange({
updates: {
Mutation: {
updateTodoDate(_result, args, cache, _info) {
const fragment = gql`
fragment _ on Todo {
id
updatedAt
}
`;
cache.writeFragment(fragment, { id: args.id, updatedAt: args.date });
},
},
},
});
cache.writeFragment 与 本地 Resolver 页 介绍过的 cache.readFragment 类似,区别在于它不是读取而是向缓存写入数据。
注意: 上例使用了
gql标签函数(见 core API 文档),因为writeFragment只接受 GraphQLDocumentNode作为输入,而不接受字符串。
从源码看其写入路径:exchanges/graphcache/src/store/store.ts 中 writeFragment 调用 _writeFragment(exchanges/graphcache/src/operations/write.ts),后者会先从文档中提取片段、用 { __typename: typename, ...data } 补全数据,再通过 store.keyOfEntity(dataToWrite) 生成实体键——如果无法生成键(缺少 id/_id 且无自定义 keys 配置),写入会被拒绝并告警。这与 规范化缓存 中自定义键的规则一致。
缓存更新不能发生在 updater 之外
缓存更新不能在 updates 的函数之外进行。如果试图把 cache 存到变量里、并在任何 updates 函数(或其他回调,如 resolvers)之外调用它的方法,Graphcache 会直接抛错。
原因在于:这些方法之所以不能被外部调用,是因为所有更新都被隔离为对 mutation 和 subscription 事件的响应式处理。Graphcache 不允许带外(out-of-band)更新,因为缓存只应代表服务器的状态——这一限制让缓存数据始终忠实于 API 结果,行为更加可预测。如果你真的在配置回调之外调用了 cache 方法,会收到 "(2) Invalid Cache Call" 错误(详见 错误说明)。
该限制的底层实现位于 exchanges/graphcache/src/store/data.ts:getCurrentDependencies 中的 invariant 断言了全局数据状态非空,错误文案正是 "Invalid Cache call: The cache may only be accessed or mutated during operations like write or query, or as part of its resolvers, updaters, or optimistic configs.";同样地,data.ts 中还有一个 invariant 会拒绝在缓存读取期间写入("Invalid Cache write: ... Accesses to cache.writeFragment, cache.updateQuery, and cache.link may not be made inside resolvers for instance.")。
任意类型上的 updater
缓存更新可以配置在任意类型上,而不仅限于 Mutation 或 Subscription 字段。不过这可能有潜在危险,是一个容易踩的坑——它之所以被允许,是因为能实现一些巧妙的技巧和变通。
给定一个任意类型上的 updater(例如 Todo.author),每当该字段被写入时我们都可以链式追加更新。该 updater 会在任何操作(mutation、query、subscription)期间被 Graphcache 触发,触发时允许我们向该字段追加更多任意更新。
注意: 如果你打算用它来实现嵌套在对象类型上的 mutation(例如
Mutation.author.updateName),请先考虑修改 schema 再使用这个特性。命名空间的 mutation 不被推荐,并且使用多个嵌套 mutation 字段会把执行顺序从顺序改为并发。
更新列表或链接:cache.updateQuery 与 cache.link
创建新实体的 mutation 很常见;在"创建"类 mutation 结果返回时更新缓存是常见的做法,因为可以避免对 API 的一次额外往返。
虽然这类 mutation 也可以返回携带列表的受影响实体,但列表通常位于 Query 根类型之上或之下的字段,意味着要发送相当大的 API 结果——当页数很多时尤其不可行。因此,大多数 schema 选择只返回刚创建的实体:
mutation NewTodo($text: String!) {
createTodo(id: $todoId, text: $text) {
id
text
}
}
如果 Query.todos 上有一个包含所有 Todo 实体的对应字段,就需要创建 updater 把新 Todo 自动加入列表:
cacheExchange({
updates: {
Mutation: {
createTodo(result, _args, cache, _info) {
const TodoList = gql`
{
todos {
id
}
}
`;
cache.updateQuery({ query: TodoList }, data => {
return {
...data,
todos: [...data.todos, result.createTodo],
};
});
},
},
},
});
这里用到 cache.updateQuery,它与 本地 Resolver 页 中的 cache.readQuery 类似:它接受一个回调,回调会收到从本地缓存读出的查询 data,我们返回一个更新后的数据版本。虽然我们可能本能地想不可变地复制并修改这份数据,但实际上直接修改它也是允许的——因为它只是缓存读出的一份副本。
需要注意:如果缓存中没有足够信息满足查询,这份 data 可能是 null。这一点很重要,因为 updater 中的 cache 方法并不会应用 resolvers——所有 resolver 都会被忽略,因此不可能意外把转换后的数据提交到缓存。例如,你可以安全地为 Todo.createdAt 添加 resolver,而不必担心 updater 误把它写进缓存内部数据结构。
从源码看,updateQuery 的实现(exchanges/graphcache/src/store/store.ts)会先通过 createRequest 构造请求并 readQuery 读取数据,然后把 updater 回调的结果交给 _write 写回;如果回调返回 null,则不会发生写入。
单独写链接:cache.link
只要更新的只是链接(即"关系"),我们也可以使用 cache.link 方法。它是 本地 Resolver 页 中 cache.resolve 的"写入等价物"。
我们可以用它更新缓存中的任何关系,所以上面的例子也可以用 cache.link 与 cache.resolve 重写,而不用 cache.updateQuery:
cacheExchange({
updates: {
Mutation: {
createTodo(result, _args, cache, _info) {
const todos = cache.resolve('Query', 'todos');
if (Array.isArray(todos)) {
cache.link('Query', 'todos', [...todos, result.createTodo]);
}
},
},
},
});
cache.link 可以与其他方法组合使用,而不仅仅是 cache.resolve,例如与 cache.inspectFields 搭配效果很好。不过,当你要写**记录(即标量值)**时,cache.writeFragment 和 cache.updateQuery 仍是仅有的可用方法。由于这类数据通常已被规范化缓存自动写入,更新链接常常是我们唯一需要做的修改。
从源码看,cache.link 的实现(exchanges/graphcache/src/store/store.ts)接受实体(key 或可键控实体)、字段名以及(可选的)参数,通过 keyOfEntity 计算实体键后用 keyOfField 组合字段键,最后调用内部 InMemoryData.writeLink 写入链接;传入的实体(或实体数组)会经 ensureLink(exchanges/graphcache/src/operations/shared.ts)转换为实体键——如果传入的实体无法生成键,会触发告警。
更新大量未知链接:cache.inspectFields
上一节我们看到了 mutation 结果进入缓存时如何更新数据(如列表),但例子只针对已知字段上的单一列表,比较简单。
在实际 schema 中分页非常常见,例如删除一个 todo 时,需要更新的列表可能变得不可知:我们无法提前知道已经访问过多少页(以及每页的变量)。事实上,这份知识不应该对 Graphcache 可见——查询 Client 是完全独立的关注点,通常与 UI 代码的某一部分放在一起。
mutation RemoveTodo($id: ID!) {
removeTodo(id: $id)
}
假设有上述 mutation,它按 ID 删除 Todo 实体。我们的应用可能通过多次向 API 发送独立查询来分页查询这些条目,这让我们很难知道应该检查哪些字段:
query PaginatedTodos($skip: Int) {
todos(skip: $skip) {
id
text
}
}
此时我们可以改用 cache.inspectFields 内省实体的字段,动态找出可能需要更新的字段。该方法的用法(见 API 文档)是传入一个 key 或可键控实体——就像 本地 Resolver 页 中 cache.keyOfEntity 接受的内容,或 cache.resolve 的第一个参数:
cacheExchange({
updates: {
Mutation: {
removeTodo(_result, args, cache, _info) {
const TodoList = gql`
query (skip: $skip) {
todos(skip: $skip) { id }
}
`;
const fields = cache
.inspectFields('Query')
.filter(field => field.fieldName === 'todos')
.forEach(field => {
cache.updateQuery(
{
query: TodoList,
variables: { skip: field.arguments.skip },
},
data => {
data.todos = data.todos.filter(todo => todo.id !== args.id);
return data;
}
);
});
},
},
},
});
为实现 removeTodo 的 updater,我们用 cache.inspectFields('Query') 获取 Query 根实体上的所有已知字段列表。每个字段被描述为包含三个属性的对象(对应 exchanges/graphcache/src/types.ts 中 FieldInfo 接口):
fieldName:字段名;本例中我们筛选所有todos列表字段。arguments:该字段的参数——由于接受参数的字段可以用不同参数多次访问,这里我们读取arguments.skip以找出所有独立的分页页。fieldKey:字段的键;当需要通过cache.resolve(entityKey, fieldKey)取回字段时很有用,可以避免反复序列化参数。
总结一下:在例子中,我们把字段列表筛选到只剩 todos 字段,然后遍历该字段的每一组 arguments,过滤所有列表以移除被删除的 Todo。
实现提示:
inspectFields在 exchanges/graphcache/src/store/store.ts 中通过InMemoryData.inspectFields(entityKey)返回字段列表;types.ts 的注释也提醒:该方法需要解码字段键,理论上比简单缓存查找更慢,建议只在 updater 中使用。
检查任意实体的字段
我们不必只检查 Query 根实体上的字段,可以向 cache.inspectFields 传入任意部分可键控实体或 key 来检查任何实体的字段。
例如,如果我们有一个 Todo 实体,想获取它所有已知字段,可以传入一个部分 Todo 实体:
cache.inspectFields({
__typename: 'Todo',
id: args.id,
});
失效实体(Invalidation)
坦白说,有时为所有 mutation 编写 updater 几乎是不可能的。我们甚至很难预测 API 收到 mutation 后会做什么——实体的更新可能改变列表的排序,或以我们无法预料的方式把条目移出列表,因为我们无法访问完整数据库在本地运行 API。
在这种情况下,更可取的做法是触发重新请求(refetch),让缓存通过把与失效数据相关的查询再次发送到 API 来自我更新。这个过程称为失效(invalidation),因为它从 Graphcache 的本地缓存数据中删除了数据。
我们可以使用 cache.invalidate 来失效整个实体或单个字段。它拥有与 cache.resolve 相同的签名(也见 本地 Resolver 页)。前面写的更新可以用一次 cache.invalidate 简化:
cacheExchange({
updates: {
Mutation: {
removeTodo(_result, args, cache, _info) {
cache.invalidate({
__typename: 'Todo',
id: args.id,
});
},
},
},
});
与其他缓存更新一样,这会导致所有使用该 Todo 实体的查询针对缓存进行更新;由于我们已经失效了它们使用的 Todo,这些查询会被重新请求并发往 API。如果启用了 Schema Awareness,这些查询的结果可能暂时以部分结果更新,但通常我们会观察到:数据被失效的查询会被重新请求,因为部分数据不再缓存。
从源码看(exchanges/graphcache/src/store/store.ts 与 exchanges/graphcache/src/operations/invalidate.ts):invalidate 先通过 keyOfEntity 生成实体键,再调用 invalidateEntity——它会检查传入字段是否存在,存在则只对 keyOfField(field, args) 这一个字段写入 undefined,不存在则遍历 inspectFields 得到的全部字段并逐一置空;若实体键生成失败会触发 invariant 19 报错。
失效单个字段
我们可能只想失效个别字段,因为也许不是所有查询都需要立即更新。可以给 cache.invalidate 传入字段(以及可选参数)来只失效单个字段。
例如,可以用它失效列表而不是失效实体本身——如果你知道修改实体会导致列表重新排序,这会很有用:
cacheExchange({
updates: {
Mutation: {
updateTodo(_result, args, cache, _info) {
const key = 'Query';
const fields = cache
.inspectFields(key)
.filter(field => field.fieldName === 'todos')
.forEach(field => {
cache.invalidate(key, field.fieldKey);
// 或者用另一种写法:
cache.invalidate(key, field.fieldName, field.arguments);
});
},
},
},
});
这个例子把 updater 挂在 Mutation.updateTodo 字段上:我们通过 cache.inspectFields 枚举所有 todos 列表字段,然后精准失效这些字段,从而让所有使用这些列表字段的查询被重新请求。
注:
field.fieldKey形式与field.fieldName + field.arguments形式等价——前者由 exchanges/graphcache/src/store/keys.ts 的keyOfField组合生成,invalidateEntity内部也正是用keyOfField(field, args)定位目标字段。
失效整个类型
我们还可以失效某一给定类型的所有实体,这在列表更新、或不确定哪个实体受影响时非常方便。只需向 invalidate 传入相关 __typename 即可:
cacheExchange({
updates: {
Mutation: {
deleteTodo(_result, args, cache, _info) {
cache.invalidate('Todo');
},
},
},
});
源码层面,当传入的是字符串、且没有字段和参数、且 resolve(entity, '__typename') 无结果时(exchanges/graphcache/src/store/store.ts),invalidate 会走 invalidateType 分支(exchanges/graphcache/src/operations/invalidate.ts):通过 getEntitiesForType(typename) 取得该类型全部实体并逐一失效。
乐观更新(Optimistic Updates)
如果我们已经知道 mutation 可能返回什么结果,为什么要等待 GraphQL API 完成 mutation 呢?
在 updates 配置之外,cacheExchange 还接受 optimistic 选项。这是一个工厂函数集合,允许我们为 mutation 创建一个"虚拟"结果。这个临时结果可以立即应用到缓存,给用户造成 mutation 已即时执行的错觉——这是减少等待时间、让应用感觉更敏捷的绝佳方法。该技术常用于一次性且假定会成功的 mutation,比如给仓库加星、给推特点赞,此时让交互尽可能即时是非常理想的。
optimistic 配置与 resolvers/updates 配置相似,区别在于它只接收一张 mutation 字段的映射。我们可以为任何 mutation 字段挂乐观函数,使其在 Client 等待 API 响应期间生成一个应用到缓存的乐观结果。乐观函数接收三个位置参数,与 resolver/updater 的参数一致,唯独没有第一个 parent 参数(因为我们没有可处理的服务器数据,数据是创建的):
args:字段被调用时携带的参数;若字段未携带参数则替换为空对象{}。cache:cache实例,提供读写本地缓存的方法,完整 API 见 API 文档。info:不应频繁使用,包含查询文档遍历的运行时信息,可用于让 resolver 可复用或获取整个查询的信息,完整 API 见 API 文档。
当运行一个包含一个或多个乐观 mutation 字段的 mutation 时,Graphcache 会捕获它们并生成即时变更应用到缓存;resolvers 函数也会像处理真实服务器结果一样被触发。
这个修改是临时的:一旦 API 结果返回,它就会被回滚,让缓存处于可应用"真实"结果的状态。
注意: 在乐观 mutation 等待 API 结果期间,所有可能改变我们乐观数据的查询都会被暂停(或者说排队),所有乐观 mutation 会在同一时刻被回滚。这意味着乐观结果可以叠加,但绝不会与配置中的"真实"数据混淆。
假设我们想为 favoriteTodo mutation 实现乐观结果:
mutation FavoriteTodo(id: $id) {
favoriteTodo(id: $id) {
id
favorite
updatedAt
}
}
mutation 相当简单,我们要做的只是创建一个模拟 API 假定返回结果的函数:
const cache = cacheExchange({
optimistic: {
favoriteTodo(args, cache, info) {
return {
__typename: 'Todo',
id: args.id,
favorite: true,
};
},
},
});
这个乐观 mutation 会被应用到缓存;如果存在针对 Mutation.favoriteTodo 的 updates 配置,它会用乐观结果执行。一旦 mutation 结果从 API 返回,这个临时变更会被回滚并丢弃。
在上面的乐观 mutation 函数中可以看到,updatedAt 不在乐观返回值里——因为我们不必(也无法)完全匹配 mutation 的选择集。Graphcache 会跳过缺失的字段,对未提供的字段使用已缓存的字段。这甚至可以作用于嵌套实体和字段。
不过,省略字段有时会导致乐观更新不生效:如果我们的乐观更新意外导致某个需要更新的查询只被部分缓存(cache miss),我们就看不到更新被应用。
有时我们需要把乐观更新应用到接受参数的字段上。比如 favorite 字段可能有一个日期截止参数:
mutation FavoriteTodo(id: $id) {
favoriteTodo(id: $id) {
id
favorite(since: ONE_MONTH_AGO)
updatedAt
}
}
解决办法是:在乐观更新函数返回的乐观结果中,把该字段写成方法:
const cache = cacheExchange({
optimistic: {
favoriteTodo(args, cache, info) {
return {
__typename: 'Todo',
id: args.id,
favorite(_args, cache, info) {
return true;
},
};
},
},
});
这个函数的签名与参数和顶层乐观函数一致,本质上就是一个嵌套乐观函数。这一能力对应 exchanges/graphcache/src/types.ts 中的 MakeFunctional 类型——返回的乐观对象中可以包含函数,它们会被作为嵌套乐观 resolver 执行。
乐观更新所需的额外变量
有时,我们无法从缓存或既有变量中取到乐观更新创建"假结果"所需的全部数据。
为此 Graphcache 提供了一个小的逃生舱:允许访问额外的变量,这些变量可以从 UI 代码传递给 mutation。例如,给定如下 mutation,我们可以添加比 mutation 声明更多的变量:
mutation UpdateTodo($id: ID!, $text: ID!) {
updateTodo(id: $id, text: $text) {
id
text
}
}
上述 mutation 只定义了 $id 和 $text 变量。Graphcache 通常按查询文档中的变量定义过滤变量(见 exchanges/graphcache/src/cacheExchange.ts,prepareForwardedOperation 中通过 filterVariables(getMainOperation(operation.query), operation.variables) 过滤),这意味着 API 永远不会收到定义之外的变量。
然而,我们仍可以向 mutation 传递额外变量(例如 { extra }),由于 $extra 未定义,它在 mutation 发送到 API 时会被过滤掉。但乐观 mutation 仍然能访问到这个变量,如下所示:
cacheExchange({
updates: {
Mutation: {
updateTodo(_result, _args, _cache, info) {
const extraVariable = info.variables.extra;
},
},
},
});
这与 exchanges/graphcache/src/types.ts 中 ResolveInfo.variables 的说明一致——它保存的是 OperationRequest 上的完整原始变量对象。
乐观更新的底层机制
从 exchanges/graphcache/src/cacheExchange.ts 可以窥见乐观更新的完整生命周期:mutation 且请求策略非 network-only 时,prepareForwardedOperation 会以乐观模式(initDataState('write', store.data, operation.key, true, false))执行一次 _write,把乐观结果写入缓存并收集依赖(cacheExchange.ts);随后这些依赖被记入 blockedDependencies,相关查询被收集并重新执行。store/data.ts 的 layer(层)机制(reserveLayer、hasLayer、commutativeKeys、squashLayer,见 data.ts)保证乐观数据与真实数据隔离、可整体回滚。当真实结果返回时,optimisticMutationCompletion$ 会把多个乐观 mutation 的结果先缓冲进 mutationResultBuffer,待全部完成后再统一清除 blockedDependencies 并批量写回真实结果(cacheExchange.ts),避免乐观数据与真实数据互相混淆。仓库中的 cacheExchange.test.ts(如 "writes optimistic mutations to the cache"、"batches optimistic mutation result application")对这些行为有完整测试覆盖。
继续阅读
本文是 Graphcache 文档"Cache Updates"篇章的完整展开。接下来可以继续阅读 Schema Awareness:它允许 Graphcache 利用 introspection 数据在缓存不完整时返回部分结果并在后台请求完整响应,从而与失效机制协同工作;其他相关主题还包括 规范化缓存、本地 Resolver 与 缓存错误处理。