apollo-client

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apollo Client 4.x Guide

Apollo Client 4.x 指南

Apollo Client is a comprehensive state management library for JavaScript that enables you to manage both local and remote data with GraphQL. Version 4.x brings improved caching, better TypeScript support, and React 19 compatibility.

Apollo Client是一款适用于JavaScript的全状态管理库，可让你通过GraphQL管理本地和远程数据。4.x版本带来了改进的缓存功能、更好的TypeScript支持以及与React 19的兼容性。

Integration Guides

集成指南

Choose the integration guide that matches your application setup:

Client-Side Apps - For client-side React applications without SSR (Vite, Create React App, etc.)
Next.js App Router - For Next.js applications using the App Router with React Server Components
React Router Framework Mode - For React Router 7 applications with streaming SSR
TanStack Start - For TanStack Start applications with modern routing

Each guide includes installation steps, configuration, and framework-specific patterns optimized for that environment.

选择与你的应用设置匹配的集成指南：

客户端应用 - 适用于无SSR的客户端React应用（Vite、Create React App等）
Next.js App Router - 适用于使用App Router和React Server Components的Next.js应用
React Router Framework Mode - 适用于带有流式SSR的React Router 7应用
TanStack Start - 适用于带有现代路由的TanStack Start应用

每个指南都包含针对该环境优化的安装步骤、配置和框架特定模式。

Quick Reference

快速参考

Basic Query

基础查询

tsx

import { gql } from "@apollo/client";
import { useQuery } from "@apollo/client/react";

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
    }
  }
`;

function UserProfile({ userId }: { userId: string }) {
  const { loading, error, data, dataState } = useQuery(GET_USER, {
    variables: { id: userId },
  });

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

  // TypeScript: dataState === "ready" provides better type narrowing than just checking data
  return <div>{data.user.name}</div>;
}

tsx

import { gql } from "@apollo/client";
import { useQuery } from "@apollo/client/react";

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
    }
  }
`;

function UserProfile({ userId }: { userId: string }) {
  const { loading, error, data, dataState } = useQuery(GET_USER, {
    variables: { id: userId },
  });

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

  // TypeScript: dataState === "ready" 比仅检查data提供更好的类型收窄
  return <div>{data.user.name}</div>;
}

Basic Mutation

基础变更

tsx

import { gql } from "@apollo/client";
import { useMutation } from "@apollo/client/react";

const CREATE_USER = gql`
  mutation CreateUser($input: CreateUserInput!) {
    createUser(input: $input) {
      id
      name
    }
  }
`;

function CreateUserForm() {
  const [createUser, { loading, error }] = useMutation(CREATE_USER);

  const handleSubmit = async (name: string) => {
    await createUser({ variables: { input: { name } } });
  };

  return <button onClick={() => handleSubmit("John")}>Create User</button>;
}

tsx

import { gql } from "@apollo/client";
import { useMutation } from "@apollo/client/react";

const CREATE_USER = gql`
  mutation CreateUser($input: CreateUserInput!) {
    createUser(input: $input) {
      id
      name
    }
  }
`;

function CreateUserForm() {
  const [createUser, { loading, error }] = useMutation(CREATE_USER);

  const handleSubmit = async (name: string) => {
    await createUser({ variables: { input: { name } } });
  };

  return <button onClick={() => handleSubmit("John")}>Create User</button>;
}

Suspense Query

Suspense查询

tsx

import { Suspense } from "react";
import { useSuspenseQuery } from "@apollo/client/react";

function UserProfile({ userId }: { userId: string }) {
  const { data } = useSuspenseQuery(GET_USER, {
    variables: { id: userId },
  });

  return <div>{data.user.name}</div>;
}

function App() {
  return (
    <Suspense fallback={<p>Loading user...</p>}>
      <UserProfile userId="1" />
    </Suspense>
  );
}

tsx

import { Suspense } from "react";
import { useSuspenseQuery } from "@apollo/client/react";

function UserProfile({ userId }: { userId: string }) {
  const { data } = useSuspenseQuery(GET_USER, {
    variables: { id: userId },
  });

  return <div>{data.user.name}</div>;
}

function App() {
  return (
    <Suspense fallback={<p>Loading user...</p>}>
      <UserProfile userId="1" />
    </Suspense>
  );
}

Reference Files

参考文档

Detailed documentation for specific topics:

TypeScript Code Generation - GraphQL Code Generator setup for type-safe operations
Queries - useQuery, useLazyQuery, polling, refetching
Suspense Hooks - useSuspenseQuery, useBackgroundQuery, useReadQuery, useLoadableQuery
Mutations - useMutation, optimistic UI, cache updates
Fragments - Fragment colocation, useFragment, useSuspenseFragment, data masking
Caching - InMemoryCache, typePolicies, cache manipulation
State Management - Reactive variables, local state
Error Handling - Error policies, error links, retries
Troubleshooting - Common issues and solutions

特定主题的详细文档：

TypeScript代码生成 - 用于类型安全操作的GraphQL Code Generator设置
查询 - useQuery、useLazyQuery、轮询、重新获取
Suspense钩子 - useSuspenseQuery、useBackgroundQuery、useReadQuery、useLoadableQuery
变更 - useMutation、乐观UI、缓存更新
片段 - 片段共置、useFragment、useSuspenseFragment、数据掩码
缓存 - InMemoryCache、typePolicies、缓存操作
状态管理 - 响应式变量、本地状态
错误处理 - 错误策略、错误链接、重试
故障排查 - 常见问题及解决方案

Key Rules

核心规则

Query Best Practices

查询最佳实践

Each page should generally only have one query, composed from colocated fragments. Use
```
useFragment
```
or
```
useSuspenseFragment
```
in all non-page-components. Use
```
@defer
```
to allow slow fields below the fold to stream in later and avoid blocking the page load.
Fragments are for colocation, not reuse. Each fragment should describe exactly the data needs of a specific component, not be shared across components for common fields. See Fragments reference for details on fragment colocation and data masking.
Always handle
```
loading
```
and
```
error
```
states in UI when using non-suspenseful hooks (
```
useQuery
```
,
```
useLazyQuery
```
). When using Suspense hooks (
```
useSuspenseQuery
```
,
```
useBackgroundQuery
```
), React handles this through
```
<Suspense>
```
boundaries and error boundaries.
Use
```
fetchPolicy
```
to control cache behavior per query
Use the TypeScript type server to look up documentation for functions and options (Apollo Client has extensive docblocks)

每个页面通常应只有一个查询，由共置的片段组成。 在所有非页面组件中使用
```
useFragment
```
或
```
useSuspenseFragment
```
。使用
```
@defer
```
允许折叠下方的慢字段稍后流式传输，避免阻塞页面加载。
片段用于共置，而非复用。 每个片段应准确描述特定组件的数据需求，而非跨组件共享通用字段。有关片段共置和数据掩码的详细信息，请参阅片段参考。
使用非Suspense钩子（
```
useQuery
```
、
```
useLazyQuery
```
）时，务必在UI中处理
```
loading
```
和
```
error
```
状态。使用Suspense钩子（
```
useSuspenseQuery
```
、
```
useBackgroundQuery
```
）时，React通过
```
<Suspense>
```
边界和错误边界处理这些状态。
使用
```
fetchPolicy
```
控制每个查询的缓存行为
使用TypeScript类型服务器查找函数和选项的文档（Apollo Client有详细的文档块）

Mutation Best Practices

变更最佳实践

If the schema permits, mutation return values should return everything necessary to update the cache. Neither manual updates nor refetching should be necessary.
If the mutation response is insufficient, carefully weigh manual cache manipulation vs refetching. Manual updates risk missing server logic. Consider optimistic updates with a granular refetch if needed.
Handle errors gracefully in the UI
Use
```
refetchQueries
```
sparingly (prefer letting the cache update automatically)

如果架构允许，变更返回值应包含更新缓存所需的所有内容。 无需手动更新或重新获取。
如果变更响应不足，请仔细权衡手动缓存操作与重新获取的利弊。手动更新可能会遗漏服务器逻辑。如有需要，可考虑结合细粒度重新获取的乐观更新。
在UI中优雅处理错误
谨慎使用
```
refetchQueries
```
（优先让缓存自动更新）

Caching Best Practices

缓存最佳实践

Configure
```
keyFields
```
for types without
```
id
```
field
Disable normalization by setting
```
keyFields: false
```
for types that don't include an identifier and are meant to group related fields under the parent
Use
```
typePolicies
```
for pagination and computed fields
Understand cache normalization to debug issues
Enable data masking for all new applications - it prevents components from accessing fragment data they don't own, enforcing proper data boundaries and preventing over-rendering

为无
```
id
```
字段的类型配置
```
keyFields
```
对于不包含标识符且旨在将相关字段分组在父级下的类型，通过设置
```
keyFields: false
```
禁用规范化
使用
```
typePolicies
```
处理分页和计算字段
了解缓存规范化以调试问题
为所有新应用启用数据掩码 - 它可防止组件访问不属于自己的片段数据，强制执行适当的数据边界并避免过度渲染

Performance

性能优化

Avoid over-fetching with proper field selection
Configure appropriate
```
fetchPolicy
```
per use case
Use
```
@defer
```
for incremental delivery of deferred query parts, and
```
@stream
```
for streaming list fields (
```
@stream
```
available in Apollo Client 4.1+)
Prefer Suspense hooks (
useSuspenseQuery
,
useBackgroundQuery
) in modern applications for better loading state handling and code simplicity

通过适当的字段选择避免过度获取
根据用例配置合适的
```
fetchPolicy
```
使用
```
@defer
```
延迟查询部分的增量交付，使用
```
@stream
```
流式传输列表字段（
```
@stream
```
在Apollo Client 4.1+中可用）
在现代应用中优先使用Suspense钩子（
useSuspenseQuery
、
useBackgroundQuery
），以获得更好的加载状态处理和代码简洁性

Ground Rules

基本准则

ALWAYS use Apollo Client 4.x patterns (not v3 or earlier)
ALWAYS wrap your app with
```
ApolloProvider
```
ALWAYS handle loading and error states when using non-suspenseful hooks
PREFER Suspense hooks (
```
useSuspenseQuery
```
,
```
useBackgroundQuery
```
) in modern applications for better DX
NEVER store Apollo Client in React state (use module-level or context)
PREFER
```
cache-first
```
for read-heavy data,
```
network-only
```
for real-time data
USE TypeScript for better type safety with GraphQL
IMPLEMENT proper cache updates instead of refetching entire queries
ADVISE the human steering you to look into Apollo DevTools when collaboratively debugging Apollo Client issues

始终使用Apollo Client 4.x模式（而非v3或更早版本）
始终用
```
ApolloProvider
```
包裹你的应用
使用非Suspense钩子时，务必处理加载和错误状态
在现代应用中优先使用Suspense钩子（
```
useSuspenseQuery
```
、
```
useBackgroundQuery
```
）以获得更好的开发体验
切勿将Apollo Client存储在React状态中（使用模块级或上下文）
对于读密集型数据优先使用
```
cache-first
```
，对于实时数据优先使用
```
network-only
```
使用TypeScript以获得更好的GraphQL类型安全性
实施适当的缓存更新，而非重新获取整个查询
当协作调试Apollo Client问题时，建议使用Apollo DevTools