在 React 18+/19 项目中用 Apollo…

适用于 React 项目接入 Apollo Client 4.x 管理 GraphQL 远端/本地数据、配置缓存、使用 Suspense 并排查错误和性能问题。

适用场景

解决思路

1. 根据应用形态选择集成指南：客户端渲染无 SSR 的 React 应用（Vite、CRA 等）使用 references/integration-client.md。
2. Next.js 使用 App Router 与 React Server Components 时使用 references/integration-nextjs.md。
3. React Router 7 流式 SSR 应用使用 references/integration-react-router.md。
4. TanStack Start 应用使用 references/integration-tanstack-start.md。
5. 按对应集成指南完成安装、配置和框架特定模式。
6. 基础查询：从 @apollo/client 导入 gql，从 @apollo/client/react 导入 useQuery；定义 GraphQL query；在组件中用 useQuery 传入 variables；处理 loading/error；需要更严格 TypeScript 类型收窄时，在访问 data 前检查 dataState === “complete”。
7. 基础变更：从 @apollo/client 导入 gql，从 @apollo/client/react 导入 useMutation；定义 mutation；用 useMutation 获取 mutate 函数；通过 createUser({ variables: { input: { name } } }) 调用并处理 UI。
8. Suspense 查询：从 @apollo/client/react 导入 useSuspenseQuery；在组件中调用并直接访问 data；用 <Suspense fallback={...}> 包裹组件。
9. 按主题查阅参考文件：TypeScript 代码生成见 references/typescript-codegen.md；查询见 references/queries.md；Suspense Hooks 见 references/suspense-hooks.md；变更见 references/mutations.md；片段见 references/fragments.md；缓存见 references/caching.md；状态管理见 references/state-management.md；错误处理见 references/error-handling.md；排障见 references/troubleshooting.md。
10. 查询最佳实践：每个页面通常只保留一个查询，并由共置片段组成；在所有非页面组件中使用 useFragment 或 useSuspenseFragment。
11. 查询最佳实践：用 @defer 让首屏以下的慢字段稍后流式传入，避免阻塞页面加载。
12. 片段用于共置而非复用：每个片段只描述某个特定组件的数据需求，不要为公共字段跨组件共享片段。
13. 非 Suspense Hook（useQuery、useLazyQuery）始终在 UI 中处理 loading 和 error 状态。
14. 使用 Suspense Hook（useSuspenseQuery、useBackgroundQuery）时，由 React 的 <Suspense> 边界和错误边界处理 loading/error。
15. 用 fetchPolicy 按查询控制缓存行为。
16. 用 TypeScript 类型服务器查询函数和选项的文档，因为 Apollo Client 有大量 docblock。
17. 变更最佳实践：如果 schema 允许，mutation 返回值应返回更新缓存所需的一切，避免手动更新或重新获取。
18. 如果 mutation 响应不足，需仔细权衡手动缓存操作与 refetching；手动更新可能遗漏服务端逻辑；如需要，考虑乐观更新加细粒度 refetch。
19. 在 UI 中优雅处理 mutation 错误。
20. 少用 refetchQueries，优先让缓存自动更新。
21. 缓存最佳实践：为没有 id 字段的类型配置 keyFields。
22. 对不含标识符且用于把相关字段归组到父级的类型，设置 keyFields: false 来禁用规范化。
23. 用 typePolicies 处理分页和计算字段。
24. 理解缓存规范化机制，以便排查问题。
25. 所有新应用都启用 data masking，防止组件访问不属于自己的片段数据，强制数据边界并防止过度渲染。
26. 性能：通过正确选择字段避免过度获取。
27. 性能：按用例配置合适的 fetchPolicy。
28. 性能：用 @defer 做延迟查询部分的增量交付，用 @stream 流式传输列表字段（@stream 需要 Apollo Client 4.1+）。
29. 性能：现代应用优先使用 Suspense Hook（useSuspenseQuery、useBackgroundQuery），获得更好的加载状态处理和代码简洁性。
30. 基本规则：始终使用 Apollo Client 4.x 模式，不要用 v3 或更早模式。
31. 基本规则：始终用 ApolloProvider 包裹应用。
32. 基本规则：使用非 Suspense Hook 时始终处理 loading 和 error 状态。
33. 基本规则：现代应用优先使用 Suspense Hook（useSuspenseQuery、useBackgroundQuery）以获得更好的 DX。
34. 基本规则：绝不要把 Apollo Client 存到 React state；使用模块级变量或 context。
35. 基本规则：读密集数据优先 cache-first，实时数据优先 network-only。
36. 基本规则：使用 TypeScript 提升 GraphQL 类型安全。
37. 基本规则：实现正确的缓存更新，而不是重新获取整个查询。
38. 基本规则：协作调试 Apollo Client 问题时，建议负责人查看 Apollo DevTools。

适用边界 · 注意事项

• 不适用于非 React 应用，或未使用 Apollo Client 4.x / GraphQL 的项目。
• 不适用于 React 18 以下的项目，或仍使用 Apollo Client v3 及更早模式的代码库。
• 如果只是管理少量不依赖 GraphQL 的本地状态，引入 Apollo Client 可能过重。