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にはクエリの形状に対応するクエリ結果が含まれます。

null値のレンダリングを避けるため、dataにアクセスする前にloadingとerrorを確認してください。

loadingがtrueの間はスケルトンコンポーネントをレンダリングします。errorが定義されている場合はエラーメッセージをレンダリングします（エラーのテキストにはerror.messageを使用します）。dataが定義され、loadingがfalseの場合にのみ、実際のコンテンツをレンダリングします。

この3状態パターン（loading / error / data）は、Apollo Clientコンポーネントの標準的な構成です。

dataオブジェクトはGraphQLクエリの構造を反映します。query { users { id name } }の場合、data.usersにアクセスすると、{id, name}オブジェクトの配列を取得できます。graphql-codegenを使って型付きフックを生成すれば、TypeScriptの型も一致します。

codegenを使わない場合、dataはanyとして型付けされます。codegenを使うと、useQueryが完全に型付けされたデータを自動的に返します。

2番目の引数として変数を渡します: useQuery(GET_USER, { variables: { id: userId } })。useEffectの依存配列と同様に、userIdが変わるとクエリが自動的に再実行されます。

Apollo Clientは、クエリと変数の一意の組み合わせごとに別々にキャッシュします。そのため、id: "1"のGET_USERとid: "2"のGET_USERには、独立したキャッシュエントリがあります。

オプションにskip: trueを渡すと、クエリの実行を防止できます: useQuery(GET_USER, { skip: !userId })。skipがtrueの場合、Apolloはリクエストを送信せず、loadingはfalse、dataはundefinedになります。

これは、SWRのnullキーやReact Queryのenabled: falseオプションに相当するApolloの機能です。

useQueryが返すrefetch関数は、フェッチポリシーに関係なくネットワークリクエストを実行します。フォームの送信後など、ユーザー操作によってサーバーのデータが変更された可能性がある場合にrefetch()を呼び出します。

refetchに新しい変数を渡すこともできます: refetch({ id: newId })で異なるパラメーターを使って再フェッチします。

オプションにnotifyOnNetworkStatusChange: trueを渡すと、ネットワークステータスの変化（取得、再フェッチ、ポーリングなど）に応じた更新を受け取れます。networkStatusフィールドには、NetworkStatus enumの数値コードが含まれます。

これにより、バックグラウンドで再フェッチが進行中でも現在のデータを隠さず、「更新中」を示す控えめなインジケーターを表示できます。

useMutation(CREATE_USER)は、[mutateFunction, { loading, error, data, reset }]を返します。ユーザーがフォームを送信したときにmutate関数を呼び出します。この関数は{ data, errors }を含むPromiseを返します。

mutate({ variables: { name: 'Alice', email: 'alice@example.com' } })を呼び出して、Mutationに入力を渡します。

useMutationのオプションにonCompleted: (data) => navigate('/dashboard')とonError: (error) => showToast(error.message)を渡します。これらのコールバックは、Mutationが解決または拒否された後に実行されます。

onCompletedはMutation結果のdataを受け取るため、画面遷移、成功メッセージの表示、フォームのリセットなどに利用できます。

mutate呼び出しのoptimisticResponseオプションは、サーバーが応答する前に合成した結果をキャッシュへ即座に書き込みます。Apolloは楽観的なデータをすぐにレンダリングし、サーバーの実際のレスポンスが到着すると置き換えます。

Mutationが失敗した場合、Apolloは楽観的更新前のキャッシュ状態へ自動的にロールバックし、UIの整合性を保ちます。

skip: trueを渡すと、useQueryはどうなりますか？

gqlタグでクエリを定義し、useQuery(QUERY, { variables, skip })を呼び出して、loading/error/dataの状態を処理します。useMutationはトリガー関数とステータスオブジェクトを返します。変数を渡して呼び出し、onCompletedとonErrorで結果を処理します。楽観的レスポンスはキャッシュを即座に更新し、失敗時には自動的にロールバックします。

skipオプションと変数に基づく再フェッチによって、条件付きおよびパラメーター付きのデータ読み込みに対応できます。