graphql-expert-best-practices

GraphQL エキスパートのベストプラクティス

GraphQL API のパフォーマンス最適化とベストプラクティスに関する包括的なガイドです。リゾルバーの最適化、クエリのパフォーマンス、データ取得パターン、スキーマ設計に関するルールを収録しており、自動リファクタリングとコード生成の指針となるよう、影響度順に優先順位を付けています。

適用するタイミング

以下の場合に、これらのガイドラインを参照してください。

• GraphQL スキーマ、リゾルバー、型定義を作成するとき
• データ取得やリゾルバーのロジックを実装するとき
• パフォーマンス上の問題がないか GraphQL コードをレビューするとき
• 既存の GraphQL API をリファクタリングするとき
• クエリの実行やリゾルバーのパフォーマンスを最適化するとき
• GraphQL サーバーのアーキテクチャを設計するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	クエリの最適化	CRITICAL	dataloader-
2	スキーマ設計	CRITICAL-HIGH	schema-
3	ミューテーション設計	CRITICAL-HIGH	mutation-
4	ページネーション	HIGH	pagination-
5	セキュリティ	CRITICAL-MEDIUM	security-
6	運用	MEDIUM	operations-

クイックリファレンス

• dataloader-n-plus-one - DataLoader を使ってクエリをバッチ処理し、N+1 によるパフォーマンスの問題を防ぎます
• query-unique-identifiers - 複合パラメーターではなく一意の識別子を使い、API の表面をシンプルにします
• schema-no-json-filters - 任意の JSON フィルタースカラーを禁止し、NoSQL インジェクションの脆弱性を防ぎます
• schema-no-binary-data - ペイロードの肥大化やメモリの問題を防ぐため、スキーマに大きなバイナリデータを含めないようにします
• schema-stable-identifiers - 情報漏えいや列挙攻撃を防ぐため、グローバルに安定した不透明な識別子を使います
• schema-structured-types - 型安全性を高めるため、非構造化の String／JSON フィールドではなく構造化型を使います
• schema-split-types-by-role - プライバシー関連フィールドの漏えいを防ぎ、実行時の認可をなくすため、ロールごとに型を分けます
• schema-prefer-deprecation - 継続的な API の進化を可能にするため、バージョン管理より非推奨化を優先します
• schema-field-overload - セキュリティ上の問題を防ぎ、API を分かりやすくするため、viewer と user のフィールドをオーバーロードしないようにします
• schema-minimize-nullable-args - API を分かりやすくし、型安全性を高めるため、nullable な引数を最小限にします
• schema-no-duplicate-fields - 信頼できる唯一の情報源を維持するため、ネストしたオブジェクト経由でアクセスできる重複フィールドを防ぎます
• mutation-no-file-uploads - メモリ枯渇やセキュリティの脆弱性を防ぐため、GraphQL 経由でファイルをアップロードしないようにします
• mutation-single-input-object - API の拡張性を高めるため、複数のスカラー引数ではなく単一の入力オブジェクト引数を使います
• mutation-union-result-types - 型安全なエラーハンドリングのため、成功型と具体的なエラー型を持つユニオン型を返します
• mutation-explicit-actions - 汎用的な更新パターンではなく、明示的なアクションを中心にミューテーションを設計します
• mutation-separate-input-types - 型安全性を高めるため、作成と更新で入力型を分けます
• mutation-avoid-validation-scalars - 複数リクエストにまたがるエラーループを防ぐため、カスタムバリデーションスカラーを避けます
• pagination-no-default-totalcount - パフォーマンスの低下を防ぐため、コネクションで totalCount をデフォルトにしないようにします
• security-complexity-limits - リソース枯渇攻撃を防ぐため、クエリの複雑度とノード数の上限を必須にします
• security-disable-introspection - スキーマの情報開示を防ぐため、本番環境ではイントロスペクションを無効にします
• operations-require-client-headers - デバッグとモニタリングのため、クライアント識別ヘッダーを必須にします

使用方法

詳しい説明とコード例については、個々のルールファイルを確認してください。

rules/dataloader-n-plus-one.md
rules/query-unique-identifiers.md
rules/schema-no-json-filters.md
rules/schema-no-binary-data.md
rules/schema-stable-identifiers.md
rules/schema-structured-types.md
rules/schema-split-types-by-role.md
rules/schema-prefer-deprecation.md
rules/schema-field-overload.md
rules/schema-minimize-nullable-args.md
rules/schema-no-duplicate-fields.md
rules/mutation-no-file-uploads.md
rules/mutation-single-input-object.md
rules/mutation-union-result-types.md
rules/mutation-explicit-actions.md
rules/mutation-separate-input-types.md
rules/mutation-avoid-validation-scalars.md
rules/pagination-no-default-totalcount.md
rules/security-complexity-limits.md
rules/security-disable-introspection.md
rules/operations-require-client-headers.md

各ルールファイルには、以下が含まれています。

• 重要である理由の簡単な説明
• そのパターンを使用する場合と使用しない場合
• 実装要件
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 追加の背景情報と参考資料