How to GraphQL React Apollo 教程:用 useMutation 的 update 回调更新 Apollo Client 缓存实现投票功能
How to GraphQL React Apollo 教程:用 useMutation 的 update 回调更新 Apollo Client 缓存实现投票功能
本文基于 HowToGraphQL 的 React + Apollo 前端教程章节《More Mutations and Updating the Store》(content/frontend/react-apollo/6-more-mutations-and-updating-the-store.md)展开,讲解在 Hacker News 克隆应用中实现“给链接投票”这一功能时的完整链路:先让 Link 组件渲染票数与投票按钮,再定义并调用 vote mutation,最后也是全篇的核心——使用 Apollo Client 命令式缓存 API(useMutation 的 update 回调、cache.readQuery / cache.writeQuery)在 mutation 完成后手动同步客户端 store,使 UI 无需刷新页面即可实时更新。读完本文,你将掌握 GraphQL mutation 后缓存失效(cache invalidation)问题的标准解法,并理解投票数据在后端(Apollo Server + Nexus + Prisma)是如何建模的。
功能背景:投票数据从后端到前端的完整链路
在教程的前一章中,我们已经实现了基于 post mutation 的“创建链接”功能(参见 content/frontend/react-apollo/3-mutations-creating-links.md)以及登录/注册功能。投票功能的数据基础由后端教程提供:在 content/backend/typescript-apollo/7-voting-and-scalars.md 中,Link 与 User 之间建立了隐式多对多关系(Link.voters 与 User.votes),vote(linkId: Int!) mutation 返回一个 Vote 类型,其中包含被投票的 link 和投了票的 user 两个字段:
type Vote {
link: Link!
user: User!
}
从后端 resolvers 的实现看,vote 会先校验 context.userId(由 Authorization 头的 JWT 解码得到,未登录直接抛出 "Cannot vote without logging in."),然后通过 Prisma 的 connect 选项把当前用户挂到该链接的 voters 关系上,最后返回 { link, user }。这解释了前端 mutation 的返回结构为什么恰好是“链接 + 用户”的组合——前端拿到的 vote 对象可以直接拼进缓存里已有的链接数据。
而前端的请求认证机制在上一章(content/frontend/react-apollo/5-authentication.md)已经搭好:authLink 通过 setContext 中间件在每次 ApolloClient 发请求前,从 localStorage 读取 AUTH_TOKEN(常量定义在 src/constants.js 中,export const AUTH_TOKEN = 'auth-token')并以 Bearer ${token} 形式附加到 authorization 请求头。因此本章的投票 mutation 不需要额外的鉴权代码,只要用户处于登录态,请求就会自动携带 token。
第一步:准备 React 组件
按照教程的一贯思路,先让组件“长好”预期功能的形状,再接线。
1. 给 Link 组件加上投票按钮与票数展示
打开 src/components/Link.js,把返回的 JSX 更新为如下形态:
import { AUTH_TOKEN } from '../constants';
// ...
const Link = (props) => {
const { link } = props;
const authToken = localStorage.getItem(AUTH_TOKEN);
return (
<div className="flex mt2 items-start">
<div className="flex items-center">
<span className="gray">{props.index + 1}.</span>
{authToken && (
<div
className="ml1 gray f11"
style={{ cursor: 'pointer' }}
onClick={() => { console.log("Clicked vote button") }}
>
▲
</div>
)}
</div>
<div className="ml1">
<div>
{link.description} ({link.url})
</div>
{(
<div className="f6 lh-copy gray">
{link.votes.length} votes | by{' '}
{link.postedBy ? link.postedBy.name : 'Unknown'}{' '}
{timeDifferenceForDate(link.createdAt)}
</div>
)}
</div>
</div>
);
};
export default Link;
这段代码做了三件事:
- 从
localStorage读取AUTH_TOKEN,只有登录用户才会渲染 ▲ 投票按钮(authToken && (...))。注意这里只是 UI 层的权限提示,真正的鉴权仍由后端的userId检查兜底; - 展示每条链接的票数
link.votes.length和发帖人名称link.postedBy.name。若链接没有关联用户,则显示Unknown; - 调用
timeDifferenceForDate(link.createdAt)把创建时间戳转成"3 hours ago"这类人类可读的相对时间。
timeDifferenceForDate 尚未实现,接下来补上。
2. 实现时间差工具函数 utils.js
在 src 目录新建 utils.js,完整代码如下。函数以毫秒为单位分档比较,依次输出 just now / less than 1 min ago / N min ago / N h ago / N days ago / N mo ago / N years ago:
function timeDifference(current, previous) {
const milliSecondsPerMinute = 60 * 1000;
const milliSecondsPerHour = milliSecondsPerMinute * 60;
const milliSecondsPerDay = milliSecondsPerHour * 24;
const milliSecondsPerMonth = milliSecondsPerDay * 30;
const milliSecondsPerYear = milliSecondsPerDay * 365;
const elapsed = current - previous;
if (elapsed < milliSecondsPerMinute / 3) {
return 'just now';
}
if (elapsed < milliSecondsPerMinute) {
return 'less than 1 min ago';
} else if (elapsed < milliSecondsPerHour) {
return (
Math.round(elapsed / milliSecondsPerMinute) +
' min ago'
);
} else if (elapsed < milliSecondsPerDay) {
return (
Math.round(elapsed / milliSecondsPerHour) + ' h ago'
);
} else if (elapsed < milliSecondsPerMonth) {
return (
Math.round(elapsed / milliSecondsPerDay) + ' days ago'
);
} else if (elapsed < milliSecondsPerYear) {
return (
Math.round(elapsed / milliSecondsPerMonth) + ' mo ago'
);
} else {
return (
Math.round(elapsed / milliSecondsPerYear) +
' years ago'
);
}
}
export function timeDifferenceForDate(date) {
const now = new Date().getTime();
const updated = new Date(date).getTime();
return timeDifference(now, updated);
}
注意分档逻辑中“月”按 30 天、“年”按 365 天近似,Math.round 保证输出是整数。回 Link.js 顶部补齐导入:
import { AUTH_TOKEN } from '../constants';
import { timeDifferenceForDate } from '../utils';
3. LinkList 传入列表下标 index
Link 要渲染自己在列表中的位置(props.index + 1),所以 LinkList.js 渲染列表时要下发 index:
return (
<div>
{data && (
<>
{data.feed.links.map((link, index) => (
<Link key={link.id} link={link} index={index} />
))}
</>
)}
</div>
);
4. 扩展 FEED_QUERY:把 votes 和 postedBy 拉进查询载荷
此时直接运行应用会报错,因为 Link.js 用到了 link.votes 和 link.postedBy,而 FEED_QUERY 还没有请求这些字段。GraphQL 的“按需取数”原则意味着:组件需要展示什么,查询就必须显式声明什么。更新 LinkList.js 中的查询定义,并把它 export 出来供其他文件复用(后面更新缓存时要按同一份文档读写缓存):
export const FEED_QUERY = gql`
{
feed {
id
links {
id
createdAt
url
description
postedBy {
id
name
}
votes {
id
user {
id
}
}
}
}
}
`;
两个细节值得注意:
votes子选择集只取了id和user { id }。这与后端Vote类型(link+user)以及 mutation 返回结构保持一致——投票的缓存项以id作为实体标识、user.id用于标识“谁投的票”;id字段不能漏。Apollo Client 的规范化缓存(normalized cache)默认以id+__typename作为实体键,缺少id会导致嵌套对象无法正确缓存与去重。
提示:如果此时拉不到
Links数据,重启 GraphQL 服务器并刷新浏览器,也可以到 GraphQL Playground 里确认接口工作是否正常。
运行应用后,链接列表即可正确展示描述、URL、票数与发帖人。
第二步:定义并调用 vote mutation
1. 定义 VOTE_MUTATION
在 Link.js 顶部添加 mutation 文档。参数 linkId 用非空 ID! 传入,返回的 vote 字段选择 id、link { id votes { id user { id } } } 与 user { id }:
const VOTE_MUTATION = gql`
mutation VoteMutation($linkId: ID!) {
vote(linkId: $linkId) {
id
link {
id
votes {
id
user {
id
}
}
}
user {
id
}
}
}
`;
这里的字段选择集是刻意对齐的:mutation 返回的 vote.link.votes 结构与 FEED_QUERY 中链接的 votes 子结构一致,这为后面直接把新票“塞进”缓存列表铺平了路。
2. 用 useMutation 接线 onClick
与前几章的 post、login mutation 完全同构:useMutation 返回一个元组,解构出执行函数 vote,把它直接挂到 ▲ 按钮的 onClick 上:
const Link = (props) => {
// ...
const [vote] = useMutation(VOTE_MUTATION, {
variables: {
linkId: link.id
}
});
return (
<div className="flex mt2 items-start">
<div className="flex items-center">
<span className="gray">{props.index + 1}.</span>
<div
className="ml1 gray f11"
style={{ cursor: 'pointer' }}
onClick={vote}
>
▲
</div>
</div>
<div className="ml1">
<div>
{link.description} ({link.url})
</div>
{authToken && (
<div className="f6 lh-copy gray">
{link.votes.length} votes | by{' '}
{link.postedBy ? link.postedBy.name : 'Unknown'}{' '}
{timeDifferenceForDate(link.createdAt)}
</div>
)}
</div>
</div>
);
};
别忘了导入依赖:
import { useMutation, gql } from '@apollo/client';
在 hackernews-react-apollo 目录运行 yarn start,点击 ▲ 按钮:网络请求成功、数据库里也确实多了一条投票记录,但页面上的票数不会变——刷新页面后才显示新票数。这正是本章要解决的问题:mutation 改动了服务端数据,但 Apollo Client 的本地缓存还停留在旧的查询结果上,LinkList 从缓存重新渲染时自然读不到新票。
注意:必须处于登录状态才能投票,否则后端 resolver 会直接抛出未登录错误。
第三步:核心知识点——用 update 回调手动更新 Apollo 缓存
Apollo Client 的核心价值主张之一就是它会自动为 GraphQL 应用创建并维护客户端缓存。大多数情况下你不需要管理缓存,但当 mutation 影响的是某个列表数据时,Apollo 无法仅凭 mutation 的返回结果推断出该更新哪条已有查询的结果,这时就需要手动介入。官方推荐的机制就是 useMutation 的 update 回调:它在 mutation 成功完成后执行,接收 (cache, { data }) 两个参数,允许你读取缓存、修改、再提交变更。
1. 给投票 mutation 加 update 回调
更新 Link.js 中的 useMutation 配置:
const Link = (props) => {
// ...
const [vote] = useMutation(VOTE_MUTATION, {
variables: {
linkId: link.id
},
update: (cache, { data: { vote } }) => {
const { feed } = cache.readQuery({
query: FEED_QUERY
});
const updatedLinks = feed.links.map((feedLink) => {
if (feedLink.id === link.id) {
return {
...feedLink,
votes: [...feedLink.votes, vote]
};
}
return feedLink;
});
cache.writeQuery({
query: FEED_QUERY,
data: {
feed: {
links: updatedLinks
}
}
});
}
});
// ...
};
这段代码逐行拆解:
cache.readQuery({ query: FEED_QUERY }):传入的就是LinkList.js里导出的那份查询文档,因此读出的是缓存中与该查询结果严格对应的数据切片({ feed })。用同一个文档读、同一个文档写,保证了读写命中同一份缓存条目;{ data: { vote } }解构:第二个参数是 mutation 的响应对象,这里用嵌套解构直接取出vote,即后端刚返回的投票对象(含id、link、user);map定位目标链接:遍历feed.links,只对id匹配的那条链接做不可变更新——展开原对象后把vote追加到votes数组末尾([...feedLink.votes, vote])。这里没有修改原数组,而是返回新对象,符合 React 对 state 不可变性的要求;cache.writeQuery(...):把更新后的feed.links整体写回缓存。写入即提交,Apollo 会感知到该查询结果变化,自动触发订阅该查询的组件(LinkList)重新渲染,票数 +1 立即呈现在 UI 上,全程没有再发一次查询。
最后一步,Link.js 要导入缓存读写所依赖的查询文档:
import { FEED_QUERY } from './LinkList';
至此,投票 mutation 完成后 store 会被正确更新,组件重渲染,UI 显示最新票数。
2. 原理层面:为什么必须手动更新?
从 Apollo Client 的工作机制看可以推断:useQuery 的结果缓存键由查询文档 + 变量共同决定。VOTE_MUTATION 返回的是一个 Vote(含 link 与 user),但 Apollo 并不知道“FEED_QUERY 的 feed.links[n].votes 列表里需要插入这个票”,因为 mutation 结果与既有查询结果之间的映射关系在 schema 层面并不唯一(同一份返回数据也可能属于分页后的一页、被过滤排除的一条等)。因此对“影响列表的 mutation”,官方模式就是在 update 回调中显式编码这条映射规则:读旧值 → 应用业务规则 → 写新值。这与 Redux 的 reducer 思路同构,只是操作对象换成了 GraphQL 规范化缓存。
3. 举一反三:给创建链接 mutation 加 update
同一个模式可以直接套用到 post mutation 上。打开 CreateLink.js(其 CREATE_LINK_MUTATION 定义与 useMutation 基础用法见 content/frontend/react-apollo/3-mutations-creating-links.md),在 useMutation 中加入 update 回调:
const [createLink] = useMutation(CREATE_LINK_MUTATION, {
variables: {
description: formState.description,
url: formState.url
},
update: (cache, { data: { post } }) => {
const data = cache.readQuery({
query: FEED_QUERY,
});
cache.writeQuery({
query: FEED_QUERY,
data: {
feed: {
links: [post, ...data.feed.links]
}
},
});
},
onCompleted: () => navigate("/")
});
投票是“在列表中间某一项上追加元素”,创建链接则是“向列表头部插入一条新记录”([post, ...data.feed.links],新链接显示在最前)。update 与 onCompleted 分工明确:前者负责缓存数据同步,后者负责导航跳转。同样需要导入查询文档:
import { FEED_QUERY } from './LinkList';
教程在此处还特别提醒一个容易踩的坑:readQuery / writeQuery 不能只传查询文档,还必须传入与原始查询一致的 variables。也就是说,你在更新缓存时锁定的到底是哪一份查询结果,取决于“文档 + 变量”这个组合。本章中 FEED_QUERY 不带变量,所以直接传文档即可;但一旦后续章节给 feed 加上过滤或分页参数,这里的读写就必须带上同样的 variables,否则读到的缓存切片就不是 LinkList 当前渲染的那份数据了。
小结与后续章节衔接
本章完整走通了“mutation + 缓存手动更新”的标准流程,可归纳为四步:
| 步骤 | 操作 | 关键 API |
|---|---|---|
| 1 | 定义 mutation 文档,返回结构对齐既有查询 | gql 模板 |
| 2 | 用 useMutation 拿到执行函数并绑定到事件 |
useMutation(document, { variables }) |
| 3 | 在 update 回调中读出目标查询的缓存切片 |
cache.readQuery({ query, variables }) |
| 4 | 按业务规则不可变地变换数据后写回 | cache.writeQuery({ query, variables, data }) |
这套模式的收益是:mutation 成功后 UI 即时反映新状态,避免了“刷新页面才看到变化”的割裂体验;代价是需要开发者为每个影响列表的 mutation 显式编写缓存更新逻辑。后续章节在此基础上继续推进:过滤、搜索链接列表(FEED_QUERY 开始携带变量,正好验证上面关于 variables 的注意点)、订阅(订阅同样依赖 AUTH_TOKEN 建立 WebSocket 认证)以及 分页。
需要说明的适用前提:本文基于 HowToGraphQL 教程的 hackernews-react-apollo 前端项目(React + Apollo Client hooks API + React Router)与 hackernews-node 后端项目(Apollo Server + Nexus + Prisma)撰写,代码以该教程仓库中的教学代码为准;文中所有路径均指向本教程仓库内的对应文档文件,便于对照原文逐行实现。