19k Star，Apollo Client 是 GraphQL 客户端的事实标准

19k Star，Apollo Client 是 GraphQL 客户端的事实标准

Apollo Client 由 Apollo GraphQL 团队维护，目前在 GitHub 上获得了 19,715 个 Star。它为 React、Angular 等前端框架提供了与 GraphQL API 交互的完整方案，覆盖数据查询、变更、缓存、本地状态管理等多个环节。

直接使用 fetch 或 axios 调用 GraphQL 端点也能跑通，但会遇到几个问题：每次都要手写查询模板字面量、相同请求缺乏去重环节、没有缓存层导致重复请求、UI 状态与远程数据的映射需要大量样板代码。Apollo Client 在这些问题上给出了封装好的方案，在实际项目中可以减少相当数量的样板代码。

GraphQL 本身只定义了查询语言和类型系统规范，不规定客户端如何发送请求、如何缓存数据、如何处理实时事件。Apollo Client 把这些基础设施问题全包了下来，这也是它能成为社区首选的原因。

安装

npm install @apollo/client graphql

@apollo/client 包含全部核心功能，graphql 用于解析查询字符串。

基本接入

创建 client 实例并通过 ApolloProvider 注入应用：

import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://your-api.com/graphql',
  cache: new InMemoryCache()
});

function App() {
  return (
    <ApolloProvider client={client}>
      <YourComponent />
    </ApolloProvider>
  );
}

ApolloProvider 基于 React Context 将 client 实例下发给整个组件树。ApolloClient 构造函数还支持传入 link 链（用于自定义请求中间件）、defaultOptions（全局默认配置）、typeDefs（本地 schema）等参数，可以按项目需要做精细控制。

useQuery 查询数据

useQuery 是使用频率最高的 Hook，调用时传入 GraphQL 查询字符串，返回 loading、error、data 三个状态值：

import { useQuery, gql } from '@apollo/client';

const GET_POSTS = gql`
  query GetPosts {
    posts {
      id
      title
      author { name }
    }
  }
`;

function PostList() {
  const { loading, error, data } = useQuery(GET_POSTS);

  if (loading) return <p>加载中...</p>;
  if (error) return <p>请求失败: {error.message}</p>;

  return data.posts.map(post => (
    <div key={post.id}>
      <h3>{post.title}</h3>
      <span>{post.author.name}</span>
    </div>
  ));
}

组件挂载后自动发起请求，loading、error、data 三种状态的切换由 Hook 内部管理。useQuery 第二个参数支持多项配置：pollInterval 可以设定轮询间隔（毫秒），skip 可以在满足条件前跳过请求，fetchPolicy 控制缓存使用策略，onCompleted 和 onError 提供回调入口。返回对象中还包含 refetch 函数，用于在任何时机手动重新拉取数据。

useMutation 与 useSubscription

useMutation 返回一个执行函数和状态对象，不会像 useQuery 那样在挂载时自动执行。数据变更由用户操作触发：

const [addPost, { loading }] = useMutation(ADD_POST);

const handleSubmit = () => {
  addPost({ variables: { title, content } });
};

mutation 完成后往往需要同步更新缓存中的数据。Apollo Client 提供了两种途径：一是在 useMutation 的 update 回调中直接读写缓存，二是通过 refetchQueries 参数指定需要重新查询的查询列表。对于需要即响应的场景，还可以配置 optimisticResponse 在服务端返回前先更新 UI，服务端确认后再用真实数据替换。

useSubscription 用于通过 WebSocket 接收服务端实时推送，适用于即时消息、数据监控等场景。前端需要配合 GraphQL-WS 或 subscriptions-transport-ws 协议建立持久连接。

规范化缓存

InMemoryCache 对每次查询结果做规范化处理，将嵌套数据拆分为扁平实体记录，以 __typename 和 id 作为唯一标识。

当同一个对象出现在多个查询结果中，缓存中只存一份。某个 mutation 更新了数据后，所有引用该对象的活跃查询会自动触发 UI 刷新，不需要手动调用 refetch。缓存命中时甚至不需要发起网络请求，用户感知的加载延迟可以做到接近零。

通过 fetchPolicy 参数可以控制单次查询的缓存策略：

• cache-first：默认值，优先读缓存
• network-only：始终请求网络，结果写入缓存
• cache-and-network：同时返回缓存结果并请求网络
• no-cache：不读写缓存

以 cache-and-network 为例，页面切换回来后用户先看到缓存的旧数据，不会面对白屏，同时后台请求最新数据，加载完成后无缝替换。这个策略在列表类页面上使用频率较高。

对于写入操作，开发者可以通过 cache.modify 直接更新缓存字段，或用 cache.evict 清除指定数据。如果项目的数据模型比较复杂，还可以通过 typePolicies 配置自定义的合并和读取逻辑。

分页

Apollo Client 的 useQuery 返回了 fetchMore 函数用于实现分页加载。常见的做法是在列表底部触发 fetchMore，将新数据追加到已有列表中。对于使用 Relay 风格连接的 GraphQL API，Apollo Client 内置了 relayStylePagination 策略，配置 typePolicies 后自动处理 cursor 和 edges 的合并逻辑，不用手动拼接数组。

错误处理

useQuery 的 errorPolicy 参数控制 GraphQL 错误的传播行为。默认值 none 下，只要有字段级错误就置 error 为非空且不返回 data。设置为 all 则允许部分数据返回，error 与 data 并存，适合对数据可用性要求较高的场景。ignore 选项忽略所有 GraphQL 错误仅处理网络错误。

对于全局错误，可以在 ApolloClient 构造时通过 link 链添加 onError 中间件，集中处理认证失效、服务端异常等情况，避免在每个组件中重复写错误处理逻辑。

Apollo Link 中间件链

Apollo Client 的请求链路基于 Apollo Link 抽象。每次 GraphQL 操作都会经过一个由多个 link 组成的链式管道。常见用法包括：

• 在请求发出前通过 setContext 添加认证头
• 通过 onError 捕获服务端错误并做统一提示
• 使用 split 按操作类型路由到不同传输方式（查询走 HTTP，订阅走 WebSocket）
• 通过 retry 对失败的请求自动重试

link 链的设计让关注点分离变得直接，认证、日志、重试各自作为独立模块组合使用。不修改业务组件就能调整请求行为。

Fragment 驱动开发

Apollo Client 支持在组件层级定义 GraphQL Fragment。每个组件声明自己所需的数据字段，父组件通过 ...FragmentName 语法将其拼入查询：

const POST_FRAGMENT = gql`
  fragment PostFields on Post {
    id
    title
    author { name }
  }
`;

function PostCard({ post }) {
  return <div>{post.title}</div>;
}

这种模式的好处是数据依赖与组件封装在同一处，修改字段时只需改对应组件，不会影响到其他不相关的查询。配合 GraphQL Code Generator 生成类型后，TypeScript 类型和查询字段自动同步，重构时编译器会帮你检查遗漏。

本地状态管理

Apollo Client 支持通过 @client 指令在 GraphQL 查询中标记本地字段，将本地 UI 状态与远程数据放在同一个查询中获取。对于已使用 Apollo Client 的项目，这能减少额外引入状态管理库的需要。

开发者工具

Apollo Client Devtools 提供浏览器扩展，可查看活跃查询的缓存状态和查询耗时，对排查性能问题比较实用。

小结

Apollo Client 对 GraphQL 客户端的核心需求覆盖得比较到位：声明式查询、自动缓存、状态同步、实时订阅。对于使用 GraphQL API 的 React 项目，它是社区积累最久、周边最成熟的选项。