# Apollo 客户端 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 组件的 Next.js 应用程序 * **[React Router 框架模式]()** \- 对于具有流式 SSR 的 React Router 7 应用程序 * **[TanStack Start]()** \- 对于具有现代路由的 TanStack Start 应用程序每个指南都包含针对该环境优化的安装步骤、配置和特定于框架的模式。 ## 快速参考 ### 基本查询从“@apollo/client”导入{gql}；从“@apollo/client/react”导入{ useQuery }；常量 GET_USER = gql` 查询 GetUser($id: ID!) { 用户（id：$id）{ 编号姓名 } } `; 函数 UserProfile({ userId }: { userId: string }) { const { 加载、错误、数据、dataState } = useQuery(GET_USER, { 变量：{ id: userId }, }); if (正在加载) return

正在加载...

; if (error) return

错误: {error.message}

; // TypeScript: dataState === "ready" 比仅仅检查数据提供更好的类型缩小返回

{data.user.name}

; } ### 基本突变从“@apollo/client”导入{gql}；从“@apollo/client/react”导入{ useMutation }；常量 CREATE_USER = gql` 突变 CreateUser($input: CreateUserInput!) { 创建用户（输入：$输入）{ 编号姓名 } } `; 函数创建用户表单（）{ const [createUser, { 加载, 错误 }] = useMutation(CREATE_USER); const handleSubmit = async (名称: 字符串) => { 等待createUser({ 变量: { 输入: { 名称 } } }); }; return ; } ### 悬念查询从“react”导入{Suspense}；从“@apollo/client/react”导入{ useSuspenseQuery }；函数 UserProfile({ userId }: { userId: string }) { const { 数据 } = useSuspenseQuery(GET_USER, { 变量：{ id: userId }, }); 返回

{data.user.name}

; } 函数应用程序（）{ 返回（正在加载用户...

}> <用户配置文件 userId="1" /> ）； } ## 参考文件特定主题的详细文档： * [TypeScript 代码生成]() \- 用于类型安全操作的 GraphQL 代码生成器设置 * [查询]() \- useQuery、useLazyQuery、轮询、重新获取 * [Suspense Hooks]() \- useSuspenseQuery、useBackgroundQuery、useReadQuery、useLoadableQuery * [Mutations]() \- useMutation、乐观 UI、缓存更新 * [Fragments]() \- 片段共置、useFragment、useSuspenseFragment、数据屏蔽 * [缓存]() \- InMemoryCache、typePolicies、缓存操作 * [状态管理]() \- 反应变量，本地状态 * [错误处理]() \- 错误策略、错误链接、重试 * [问题排查]() \- 常见问题及解决方案 ## 关键规则 ### 查询最佳实践 * **每个页面通常应该只有一个查询，由并置片段组成。** 在所有非页面组件中使用 `useFragment` 或 `useSuspenseFragment`。使用“@defer”允许折叠下方的慢速字段稍后流入并避免阻塞页面加载。 * **片段用于共置，而不是重用。** 每个片段应准确描述特定组件的数据需求，而不是在公共字段的组件之间共享。有关片段共置和数据屏蔽的详细信息，请参阅[片段参考]()。 * 使用无悬念钩子（`useQuery`、`useLazyQuery`）时，始终处理 UI 中的 `loading` 和 `error` 状态。当使用 Suspense 钩子（`useSuspenseQuery`、`useBackgroundQuery`）时，React 通过 `` 边界和错误边界来处理这个问题。 * 使用`fetchPolicy`来控制每个查询的缓存行为 * 使用 TypeScript 类型服务器查找函数和选项的文档（Apollo 客户端有大量的文档块） ### 突变最佳实践 * **如果架构允许，突变返回值应返回更新缓存所需的所有内容。** 手动更新或重新获取都不是必要的。 * 如果突变响应不足，请仔细权衡手动缓存操作与重新获取。手动更新存在丢失服务器逻辑的风险。如果需要，请考虑通过粒度重新获取进行乐观更新。 * 在 UI 中优雅地处理错误 * 谨慎使用 `refetchQueries` （最好让缓存自动更新） ### 缓存最佳实践 * 为没有“id”字段的类型配置“keyFields” * 通过为不包含标识符且旨在将相关字段分组到父项下的类型设置“keyFields: false”来禁用规范化 * 使用“typePolicies”进行分页和计算字段 * 了解缓存规范化以调试问题 * **为所有新应用程序启用[数据屏蔽]()** \ - 它防止组件访问它们不拥有的片段数据，强制执行适当的数据边界并防止过度渲染 ### 性能 * 通过正确的字段选择避免过度获取 * 根据用例配置适当的“fetchPolicy” * 使用“@defer”来增量交付延迟查询部分，使用“@stream”来流式传输列表字段（“@stream”在 Apollo Client 4.1+ 中可用） * **在现代应用程序中更喜欢 Suspense hooks（`useSuspenseQuery`、`useBackgroundQuery`）**，以获得更好的加载状态处理和代码简单性 ## 基本规则 * 始终使用 Apollo Client 4.x 模式（不是 v3 或更早版本） * 始终使用 `ApolloProvider` 包装您的应用程序 * 使用无悬念钩子时始终处理加载和错误状态 * 在现代应用程序中首选 Suspense hooks（`useSuspenseQuery`、`useBackgroundQuery`）以获得更好的 DX * 切勿将 Apollo Client 存储在 React 状态（使用模块级或上下文） * 对于读取量大的数据，首选“缓存优先”，对于实时数据，首选“仅网络” * 使用 TypeScript 通过 GraphQL 获得更好的类型安全性 * 实施适当的缓存更新而不是重新获取整个查询 * 建议人工指导您在协作调试 Apollo 客户端问题时查看 Apollo DevTools

阿波罗客户端

包含技能