apollo-client

Apollo Client 4.x 指南

Apollo Client 是一个全面的 JavaScript 状态管理库，可通过 GraphQL 管理本地和远程数据。4.x 版本改进了缓存，提供了更好的 TypeScript 支持，并兼容 React 19。

集成指南

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

• 客户端应用 - 适用于不使用 SSR 的客户端 React 应用（Vite、Create React App 等）
• Next.js App Router - 适用于使用 App Router 和 React Server Components 的 Next.js 应用
• React Router 框架模式 - 适用于使用流式 SSR 的 React Router 7 应用
• TanStack Start - 适用于使用现代路由的 TanStack Start 应用

每份指南都包含针对相应环境优化的安装步骤、配置和框架专属模式。

快速参考

基本查询

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 note: for stricter type narrowing, you can also check `dataState === "complete"` before accessing data
  return <div>{data?.user.name}</div>;
}

基本变更

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 查询

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

参考文件

特定主题的详细文档：

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

关键规则

查询最佳实践

• 每个页面通常只应有一个查询，由就近 colocate 的片段组成。 在所有非页面组件中使用 useFragment 或 useSuspenseFragment。使用 @defer 让首屏以下加载较慢的字段稍后流式传入，避免阻塞页面加载。
• 片段用于就近 colocate，而非复用。 每个片段都应准确描述特定组件所需的数据，而不应为了共享公共字段而在多个组件间复用。有关片段就近 colocate 和数据屏蔽的详情，请参阅片段参考。
• 使用非 Suspense 钩子（useQuery、useLazyQuery）时，始终在 UI 中处理 loading 和 error 状态。使用 Suspense 钩子（useSuspenseQuery、useBackgroundQuery）时，React 会通过 <Suspense> 边界和错误边界处理这些状态。
• 使用 fetchPolicy 控制每个查询的缓存行为
• 使用 TypeScript 类型服务器查找函数和选项的文档（Apollo Client 含有大量文档注释）

变更最佳实践

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

缓存最佳实践

• 为没有 id 字段的类型配置 keyFields
• 对不包含标识符、且旨在将相关字段归组到父级下的类型，将 keyFields: false 设为不规范化
• 使用 typePolicies 处理分页和计算字段
• 理解缓存规范化，以便调试问题
• 为所有新应用启用 数据屏蔽——它可阻止组件访问自身不拥有的片段数据，从而确保正确的数据边界并避免过度渲染

性能

• 正确选择字段，避免过度获取数据
• 根据具体用例配置合适的 fetchPolicy
• 使用 @defer 增量传递延迟查询部分，并使用 @stream 流式传递列表字段（@stream 适用于 Apollo Client 4.1+）
• 在现代应用中优先使用 Suspense 钩子（useSuspenseQuery、useBackgroundQuery），以便更好地处理加载状态并简化代码

基本准则

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