API 设计 / 系统课时

接入 Apollo Client 4

接入 Apollo Client 4

本课把 React + TypeScript 项目接入 Apollo Client 4:配置 HTTP 链路、规范化缓存、统一错误处理与 React Provider,并用一个不依赖业务字段的查询验证客户端能够访问 GraphQL 端点。

学习目标

  • 安装 Apollo Client 4 所需依赖,并区分核心包与 React 入口。
  • 配置 HttpLink、InMemoryCache 与 ErrorLink,建立可复用客户端实例。
  • 在 React 中注入客户端并用 TypeScript 查询完成端到端验证。

安装并确认依赖

下面假设你已经有一个可运行的 React + TypeScript 项目,并且 GraphQL 服务暴露了 HTTP 端点。Apollo Client 4 除了 @apollo/client 和 graphql,还需要 rxjs 作为顶层依赖。

bash
npm install @apollo/client@^4 graphql rxjs

预期输出

text
added <VALUE> packages, and audited <VALUE> packages in <TIME>

包数量和耗时会随锁文件、npm 版本与本地缓存变化;关键是命令以退出码 0 结束,并且三个依赖都进入项目依赖树。

配置链路、缓存与错误处理

先把服务地址放进 Vite 环境变量。开发环境示例使用本机服务;如果前后端不同源,还需要服务端正确配置 CORS。

text
VITE_GRAPHQL_URL=http://localhost:4000/graphql

创建 src/apollo.ts。HttpLink 是真正发出 HTTP 请求的终止链路,ErrorLink 在响应返回时统一记录错误,InMemoryCache 则负责查询结果的规范化缓存。

ts
import { ApolloClient, HttpLink, InMemoryCache } from "@apollo/client";
import { CombinedGraphQLErrors, ServerError } from "@apollo/client/errors";
import { ErrorLink } from "@apollo/client/link/error";

const errorLink = new ErrorLink(({ error, operation }) => {
  if (CombinedGraphQLErrors.is(error)) {
    for (const item of error.errors) {
      console.error(`[GraphQL:${operation.operationName}] ${item.message}`);
    }
    return;
  }

  if (ServerError.is(error)) {
    console.error(
      `[HTTP:${operation.operationName}] ${error.statusCode} ${error.message}`,
    );
    return;
  }

  console.error(`[Network:${operation.operationName}] ${error.message}`);
});

const httpLink = new HttpLink({
  uri: import.meta.env.VITE_GRAPHQL_URL ?? "/graphql",
});

export const client = new ApolloClient({
  link: errorLink.concat(httpLink),
  cache: new InMemoryCache(),
});

这段配置的生效行为是:操作先经过 ErrorLink 再由 HttpLink 发出,请求结果写入 InMemoryCache;发生 GraphQL、HTTP 或其他网络错误时,错误链路会按类型记录信息,但不会替代组件自己的错误界面。

接入 React 与 TypeScript

在组件中用 TypedDocumentNode 同时描述结果类型和变量类型。这里查询根对象的 __typename,因此不依赖你的业务 Schema 字段,适合做最小连通性验证。

tsx
import { gql, type TypedDocumentNode } from "@apollo/client";
import { useQuery } from "@apollo/client/react";

type ConnectivityData = {
  __typename: string;
};

type ConnectivityVariables = Record<string, never>;

const CONNECTIVITY_QUERY: TypedDocumentNode<
  ConnectivityData,
  ConnectivityVariables
> = gql`
  query Connectivity {
    __typename
  }
`;

export default function App() {
  const { data, loading, error } = useQuery(CONNECTIVITY_QUERY);

  if (loading) return <p>Connecting...</p>;
  if (error) return <p>GraphQL error: {error.message}</p>;

  return <p>GraphQL ready: {data?.__typename}</p>;
}

再在应用入口用 ApolloProvider 注入前面创建的客户端。Apollo Client 4 的 React 组件与 Hooks 从 @apollo/client/react 导入。

tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { ApolloProvider } from "@apollo/client/react";
import App from "./App";
import { client } from "./apollo";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <ApolloProvider client={client}>
      <App />
    </ApolloProvider>
  </StrictMode>,
);

预期结果是页面先短暂显示连接状态,服务可访问时随后显示根查询类型名称。

text
GraphQL ready: <VALUE>

<VALUE> 通常是根查询类型名,具体名称由服务端 Schema 决定。

运行并定位常见失败

启动开发服务器,并在浏览器打开 Vite 给出的地址。

bash
npm run dev

预期输出

text
VITE v<VALUE> ready in <TIME>
Local: http://localhost:<PORT>/

如果页面显示网络错误,先确认 VITE_GRAPHQL_URL 指向真实端点,并在修改环境变量后重启开发服务器;跨域项目再检查 CORS。若 HTTP 已成功但返回 GraphQL 错误,应查看 CombinedGraphQLErrors 中的消息,而不是把它当成网络故障。

InMemoryCache 适合大多数项目作为起点,但规范化缓存依赖对象拥有稳定身份。业务类型没有稳定 id,或唯一键由多个字段组成时,应再通过 typePolicies 明确缓存键,否则同一业务实体可能无法可靠合并。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

接入 Apollo Client 4

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通