useQuery 与 useMutation 钩子

来自 @apollo/client 的 gql 模板标签会在模块加载时，将 GraphQL 查询字符串解析为 DocumentNode。在组件外定义查询：const GET_USERS = gql`query GetUsers { users { id name email } }`。

注意：在生产代码中，请使用由 gql 包裹的单引号字符串，将其作为带标签的模板使用。gql 标签在 JavaScript 源代码中接受模板字面量语法。

useQuery(GET_USERS) 返回 { loading, error, data, refetch, fetchMore, networkStatus }。loading 在初始获取期间为 true。error 包含任何 GraphQL 错误或网络错误。data 包含与查询结构匹配的查询结果。

访问 data 前，请先检查 loading 和 error，以避免渲染空值。

当 loading 为 true 时，渲染骨架组件。如果 error 已定义，则渲染错误消息（访问 error.message 获取错误文本）。只有在 data 已定义且 loading 为 false 时，才渲染实际内容。

这种三状态模式（loading / error / data）是 Apollo Client 组件的标准结构。

data 对象与 GraphQL 查询结构保持一致。对于 query { users { id name } }，请访问 data.users；它是由 {id, name} 对象组成的数组。如果使用 graphql-codegen 生成带类型的钩子，TypeScript 类型就会匹配。

不使用代码生成时，data 的类型是 any。使用代码生成后，useQuery 会自动返回完整类型的数据。

将变量作为第二个参数传入：useQuery(GET_USER, { variables: { id: userId } })。当 userId 发生变化时，查询会自动重新运行，就像 useEffect 依赖数组一样。

Apollo Client 会分别缓存查询 + 变量的每种唯一组合，因此 GET_USER 使用 id: "1" 和 id: "2" 时，会有相互独立的缓存条目。

在选项中传入 skip: true，可以阻止查询运行：useQuery(GET_USER, { skip: !userId })。当 skip 为 true 时，Apollo 不会发出请求，loading 为 false，data 为 undefined。

这相当于 SWR 的 null 键和 React Query 的 enabled: false 选项。

useQuery 返回的 refetch 函数会触发网络请求，而不受获取策略影响。例如，在提交表单等可能改变服务器数据的用户操作后调用 refetch()。

可以向 refetch 传入新变量：refetch({ id: newId })，以使用不同参数重新获取数据。

在选项中传入 notifyOnNetworkStatusChange: true，即可在网络状态发生变化时（获取、重新获取、轮询等）接收更新。networkStatus 字段包含来自 NetworkStatus 枚举的数字代码。

这样可以在后台重新获取进行期间显示细微的“正在刷新”指示，而不会隐藏当前数据。

useMutation(CREATE_USER) 返回 [mutateFunction, { loading, error, data, reset }]。用户提交表单时会调用变更函数。它返回一个包含 { data, errors } 的 Promise。

调用 mutate({ variables: { name: 'Alice', email: 'alice@example.com' } })，即可将输入传给变更。

将 onCompleted: (data) => navigate('/dashboard') 和 onError: (error) => showToast(error.message) 传给 useMutation 选项。这些回调会在变更完成或拒绝后触发。

onCompleted 会接收变更结果数据，可用于触发导航、显示成功消息或重置表单。

mutate 调用中的 optimisticResponse 选项会在服务器响应之前，立即将模拟结果写入缓存。Apollo 会立即渲染乐观数据，服务器响应到达后再将其替换为真实响应。

如果变更失败，Apollo 会自动回滚到乐观更新前的缓存状态，使界面保持一致。

传入 skip: true 后，useQuery 会发生什么？

使用 gql 标签定义查询，调用 useQuery(QUERY, { variables, skip })，并处理 loading、error、data 状态。useMutation 会返回触发函数和状态对象；使用变量调用它，并通过 onCompleted 和 onError 处理结果。乐观响应会立即更新缓存，失败时自动回滚。

skip 选项和由变量驱动的重新获取可以处理条件式和参数化的数据加载。