wp-headless-and-wpgraphql

WordPress ヘッドレスおよび WPGraphQL スキル

概要

WPGraphQL または関連 API を通じてコンテンツを公開するヘッドレス WordPress プロジェクト向けの体系的なレビューガイダンスです。基本原則： スキーマは永続性のあるコンテンツ境界と予測可能なフロントエンドのニーズを反映し、認証、プレビュー、キャッシュ、ビルドパイプラインでは信頼境界と無効化ルールを明確にする必要があります。

使用する場面

次の場合に使用します：

• WPGraphQL を利用するテーマ、プラグイン、ヘッドレス連携をレビューする
• カスタムスキーマ拡張とリゾルバーコードを監査する
• WordPress コンテンツのフロントエンドでのデータ取得パターンをレビューする
• プレビュー、下書き、認証、再検証のフローを計画する
• ビルドパイプライン、Webhook による無効化、永続クエリの設定を確認する

次の場合には使用しないでください：

• GraphQL の公開範囲を持たない、REST API のみを使用する従来型の WordPress 連携（wp-rest-api-development を使用）
• ヘッドレスフロントエンドに関する懸念のない ACF フィールドグループの設計（wp-acf-and-content-modeling を使用）
• 分離されたフロントエンドを持たない、一般的なプラグインアーキテクチャのレビュー（wp-plugin-development を使用）
• Playground のみを使用するデモ環境の設定（wp-playground-development を使用）

コードレビューワークフロー

1. 連携範囲を特定する

   • WPGraphQL プラグインの使用状況とバージョンに関する前提
   • カスタムスキーマの登録（register_graphql_field、register_graphql_connection、register_graphql_object_type）
   • フロントエンドのクエリ、フラグメント、ルート／データローダー
   • プレビュー、認証、Webhook、キャッシュ無効化のフロー

2. まずデータモデルの境界を確認する

   • GraphQL の構造は実際のコンテンツモデルを反映していますか？
   • タクソノミー／CPT／オプションは、偶発的ではなく意図的に公開されていますか？
   • その場しのぎのリゾルバーロジックではなく、永続性のあるスキーマ設計でフロントエンドのニーズに対応していますか？

3. 認証とプレビューの挙動をレビューする

   • 下書き、リビジョン、非公開コンテンツ、プレビュートークンを読み取れるのは誰ですか？
   • フロントエンドのプレビューエンドポイントでは、権限チェックとトークン検証が明示されていますか？
   • 範囲が広すぎるクエリやキャッシュを通じて、未公開コンテンツが漏えいしていませんか？

4. クエリとリゾルバーの効率をレビューする

   • N+1 リゾルバーパターン
   • コストの高いメタデータ検索や、上限のないコネクション
   • フィールドレベルのガードやページネーションのデフォルト設定の不足
   • スキーマやフラグメントの設計が原因で発生する過剰なデータ取得

5. キャッシュとビルドの無効化をレビューする

   • オリジンキャッシュ、アプリケーションキャッシュ、CDN キャッシュの境界が明確であること
   • 再検証／Webhook の挙動が決定的であること
   • 編集のたびに手動でキャッシュを無効化する必要があるという前提が、ビルドパイプラインにないこと

6. 指摘事項を分類する

   • CRITICAL： 未公開コンテンツの露出、安全でないプレビュー／認証フロー、データ漏えいや本番環境の不安定化につながる上限のないリゾルバー
   • WARNING： 脆弱なスキーマモデリング、コストの高いリゾルバー、ページネーションの不足、無効化ルールの不備、不安定なフィールド構造へのフロントエンドの強い依存
   • INFO： 命名、フラグメント、スキーマドキュメント、永続クエリの運用、ビルドの可観測性を改善できる可能性

ファイルタイプ別の確認項目

WPGraphQL スキーマ拡張

• CRITICAL：明示的な権限チェックなしで、スキーマが非公開データ／メタデータを公開している
• WARNING：リゾルバーがバッチ処理やキャッシュなしでノードごとに get_post_meta() ／ WP_Query を繰り返し実行している
• WARNING：フィールド名や戻り値の型がドメインモデルと一致せず、フロントエンドで回避策が必要になっている
• INFO：関連フィールドを、個別のスカラー値として散在させるのではなく、オブジェクト型やコネクションにまとめられる可能性

フロントエンドのクエリレイヤー

• WARNING：ルート／ページのクエリが、実際に描画されるフィールドが少数なのに、大きなツリーを取得している
• WARNING：テンプレート／ルート間でフラグメントが一貫性なく重複している
• WARNING：プレビューモードと本番モードが安全でない形でキャッシュを共有している
• INFO：共通フラグメントを永続化するか、コンテンツタイプごとにクエリドキュメントを一元化できる可能性

プレビューと認証フロー

• CRITICAL：プレビューエンドポイントは、権限トークンの所有者を検証せず、スラッグまたは投稿 ID のみを信頼します
• CRITICAL：下書きや非公開コンテンツが CDN またはアプリケーション層でキャッシュ可能になります
• WARNING：エディターのプレビュー通信と一般公開の通信が区別されていません
• INFO：プレビューのライフサイクル、トークンの有効期限、キャッシュ回避のルールをより明確に文書化できます

ビルド／再検証／Webhook

• WARNING：コンテンツが変更されるたびに、対象を絞らず全体を再ビルドします
• WARNING：Webhook は、どのルートやコンテンツが変更の影響を受けるかを特定しません
• WARNING：再検証イベントの失敗時に、再試行または検証する手段がありません
• INFO：デバッグ用に、イベントログや再送可能な Webhook 配信を追加できます

すばやく検出するための検索パターン（HEADLESS-21）

以下の rg コマンドを使うと、ヘッドレスおよび WPGraphQL の対象箇所をすばやく特定できます。

スキーマとリゾルバーの検出

rg -n "register_graphql_(field|fields|connection|object_type|interface_type|union_type|enum_type)|graphql_register_types" . -g '*.{php}'
rg -n "WPGraphQL|graphql" . -g '*.{php,js,jsx,ts,tsx,md,yml,yaml}'

フロントエンドクエリの検出

rg -n "gql`|graphql`|useQuery\(|ApolloClient|@apollo/client|urql|graphql-request|getStaticProps|getServerSideProps|generateStaticParams" . -g '*.{js,jsx,ts,tsx}'
rg -n "preview|draftMode|draftMode\(|revalidate|revalidatePath|revalidateTag" . -g '*.{js,jsx,ts,tsx}'

リスクのあるデータとキャッシュのパターン

rg -n "get_post_meta\(|WP_Query\(|meta_query|posts_per_page\s*=>\s*-1" . -g '*.{php}'
rg -n "webhook|revalidation|x-vercel|x-signature|secret|persisted query|persistedQuery" . -g '*.{php,js,jsx,ts,tsx,yml,yaml}'

参考ファイル

• references/graphql-schema-and-modeling.md - スキーマの境界、CPT／タクソノミーのマッピング、コネクション設計、リゾルバーパターン
• references/auth-preview-and-drafts.md - プレビューモード、非公開コンテンツ、認証の境界、キャッシュ回避のルール
• references/caching-builds-and-webhooks.md - 永続化クエリ、キャッシュレイヤー、ルートの再検証、Webhook 配信の設計

出力形式（HEADLESS-23）

検出事項ごとに、以下を含めてください。

1. 重大度：CRITICAL、WARNING、または INFO
2. ファイルと行番号
3. ヘッドレス／WPGraphQL のリスクの概要
4. スキーマ設計、フロントエンドの正確性、または本番環境の安定性にとって重要な理由
5. より安全な推奨パターン

問題が見つからなかった場合は、その旨を明確に伝え、プレビュー文書の不備、無効化状況の可視性の欠如、またはフロントエンドの進化に伴って乖離する可能性のあるスキーマ領域など、残存リスクにも言及してください。