How to GraphQL React Apollo 教程:用 useMutation 的 update 回调更新 Apollo Client 缓存实现投票功能

原创2026-09-24 12:31:391,330 阅读

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
          }
        }
      });
    }
  });

  // ...
};

这段代码逐行拆解:

  1. cache.readQuery({ query: FEED_QUERY }):传入的就是 LinkList.js 里导出的那份查询文档,因此读出的是缓存中与该查询结果严格对应的数据切片({ feed })。用同一个文档读、同一个文档写,保证了读写命中同一份缓存条目;
  2. { data: { vote } } 解构:第二个参数是 mutation 的响应对象,这里用嵌套解构直接取出 vote,即后端刚返回的投票对象(含 id、link、user);
  3. map 定位目标链接:遍历 feed.links,只对 id 匹配的那条链接做不可变更新——展开原对象后把 vote 追加到 votes 数组末尾([...feedLink.votes, vote])。这里没有修改原数组,而是返回新对象,符合 React 对 state 不可变性的要求;
  4. 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)撰写,代码以该教程仓库中的教学代码为准;文中所有路径均指向本教程仓库内的对应文档文件,便于对照原文逐行实现。

登录后查看全文
howtographql