紳士の用語集
GraphQLの新しいデータ取得標準は、最近人気が出てきました。 現在、この技術の開発が活発に議論されており、ますます多くの新しいツールが登場しています。 GraphQLの長所の1つは、APIで利用可能なデータを記述するための汎用言語を開発チームに提供することです。 しかし、クエリ言語自体とテクノロジー全体について、どのような用語で議論すべきでしょうか？
GraphQL仕様には、 GraphQLのすべての側面に関するほぼ包括的な用語セットが含まれています。 しかし、仕様は非常に膨大です。 この記事では、具体的な例を使用して最も重要な概念と用語を見つけます。これらは専門家レベルでGraphQLを議論するのに十分です。
注-この記事は、GraphQLをゼロから学習するための最良の選択ではありません。 まず、 graphql.orgの資料に精通し、優れたコースでGraphQLを試し、Learn Apolloを試し、記事に戻って専門用語の言語に没頭することをお勧めします。
主要なGraphQLクエリ
多くの場合、クエリはGraphQLサーバーに送られるすべてのものです。 これについていくらか混乱があります。 サーバーが要求するタスクは何ですか？ データのクエリ（クエリ）、突然変異（突然変異）、またはサブスクリプション（サブスクリプション）です。 「リクエスト」という言葉は、HTTPおよびトランスポート層の理解において、ネットワークリクエストに強く関連付けられています。 したがって、いくつかの一般的な概念から始める必要があります。
- GraphQLドキュメント（GraphQLドキュメント）。 1つ以上の操作またはフラグメントを説明するGraphQl文字列。
- 運営 GraphQL実行可能ファイルが解釈する単一のデータ要求、突然変異、またはサブスクリプション。
最も単純な操作は何で構成されていますか？ たとえば、非常に単純なGraphQLドキュメントを取り上げます。
図 単純なリクエストのコンポーネント。
以下は、要求されたデータを記述するメインのGraphQL構成体です。
- 野原 JSON応答のフィールドになる、要求されたデータの単位。 これらの部分は「フィールド」と呼ばれますが、クエリの構造の奥深くにあることに注意してください。 操作の上部にあるフィールドは、より深いフィールドと同じように機能します。
- 引数 特定のフィールドに関連付けられたキーと値のペアのセット。 それらはサーバーフィールドハンドラーに転送され、データの受信に影響します。 引数は、上記のリテラルまたは次の例のような変数です。 ネストレベルに関係なく、どのフィールドにも引数を指定できることに注意してください。
上記のクエリは、GraphQLのやや省略された形式であり、データの必要性を可能な限り簡潔に表すことができます。 ただし、GraphQL操作には3つの追加部分が含まれる場合があります。 データの要求とは異なるアクションを実行する必要がある場合、または動的に生成された変数を送信する必要がある場合に使用されます。
次の例は、これらのすべての部分を示しています。
図 より詳細なリクエストとそのコンポーネント。
- 操作のタイプ（操作タイプ）。 query 、 mutation 、 subscriptionの3つの値のいずれかが可能です。これは、実行される操作のタイプを示します。 さまざまな操作の言語構造は似ていますが、GraphQL仕様では、サーバー上でさまざまな実行モードを提供しています。
- 操作の名前（操作名）。 命名は、サーバーでのデバッグとログ記録に便利です。 ネットワークログに問題がある場合、またはApollo OpticsなどのツールがGraphQLサーバーで問題を示している場合、リクエストの内容を解析するよりも、プロジェクト内の問題のリクエストを名前で見つける方が簡単です。 操作の名前は、プログラミング言語の関数の名前に似ています。
- 変数の定義（変数の定義）。 GraphQLクエリには、サーバーへのさまざまな呼び出しで変化する動的部分を含めることができますが、クエリテキストは一定のままです。 これらはクエリ変数です 。 GraphQLには静的型付けがあり、変数の値を確認できます。 このセクションでは、変数の型が宣言されています。
変数は、トランスポートレベルで受け入れられる形式で、リクエストテキストとは別に送信されます。 最近のGraphQL実装では、通常JSONが使用されます。 前述のクエリでは、変数を持つオブジェクトは次のようになります。
図 変数を持つオブジェクトの例。
ご覧のとおり、キーは変数の説明で指定された名前と一致します。 値は、列挙型Episode
から取得されます。
- 変数 GraphQL操作に関連付けられた値の辞書。 動的操作パラメーターが含まれます。
別の基本的な概念はあまり言及されていませんが、GraphQLの技術的な側面を議論する際に重要です-中括弧で囲まれているのは何ですか？
用語選択セットは、GraphQL仕様で常に使用されています。 GraphQLの再帰的な性質が接続されているため、ネストされたクエリが可能です。
- 選択（選択セット）。 操作または別のフィールド内で要求されたフィールドのセット。 フィールドがオブジェクトのデータ型を返す場合、フィールドの選択を指定する必要があります。 対照的に、
Int
型およびString
型のスカラーフィールドは選択を指定できません。
フラグメント
スニペットは、GraphQLにさらに多くの機能をもたらします。 しかし、新しい概念が来ています。
- フラグメント定義。 GraphQLフラグメントを説明するGraphQLドキュメントの一部。 後で説明するインラインフラグメントとは対照的に、名前付きフラグメントとも呼ばれます。
- フラグメント名 各フラグメントには、ドキュメント内で一意の名前が付けられています。 操作または別のフラグメントでフラグメントを参照するために使用されます。 この名前は、操作の名前と同様に、サーバーへのログオンに便利に使用されます。 したがって、フラグメントの目的を示す明確な名前を付けることをお勧めします。 クエリを最適化する必要がある場合、正しく選択された名前を使用すると、フラグメントが指定されているコード内の場所を見つけやすくなります。
- タイプへの適用性 （タイプ条件）。 常にクエリ、突然変異、サブスクリプションのいずれかのタイプで始まるGraphQL操作とは異なり、フラグメントはさまざまな選択で使用できます。 フラグメントがスキームに準拠しているかどうかを独自に検証できるようにするために、フラグメントが適用可能なユーザーデータタイプが示されます。
操作でフラグメントを使用する
フラグメントは、操作以外では特に有用ではありません。 以下に示すように、フラグメントを挿入するには2つの方法があります。
図 リクエスト内の2種類のフラグメント。
- フラグメントスプレッド 操作または別のフラグメントにフラグメントを挿入するには、フラグメント名の前に
…
が示され…
。 これはスイープと呼ばれます。 フラグメントと同じタイプに適用されるサンプルに存在する場合があります。 - インラインフラグメント 選択が適用されるタイプに応じて、選択にフィールドを追加します。 これは、外部フラグメント定義を作成しません。 インラインフラグメントは名前付きフラグメントに似ていますが、リクエスト自体で指定されます。 名前付きフラグメントとの違いは、データ型を指定する必要がないことです。 後で示すように、多くの場合、このようなフラグメントはディレクティブとともに使用されます。
指令
ディレクティブを使用して、GraphQLサーバーの追加機能が実装されます。 ディレクティブは結果の値には影響しませんが、返されるデータの構成と、場合によっては受信方法に影響を与える可能性があります。 ディレクティブはクエリのほぼどこでも見つけることができますが、この記事では現在のGraphQL仕様で定義されているskipおよびincludeディレクティブについてのみ言及しています。
図 示されているデザインは、1回のリクエストで見つかることはほとんどありませんが、このフォームで一度に便利にデモンストレーションされます。
この図は、 skip
およびinclude
ディレクティブを使用できる場所の無関係な例を示しています。 GraphQL実行可能ファイルの条件を設定して、フィールドを無視し、結果に値を含めません。 ディレクティブ構文は公開されており、さまざまなGraphQL実装により、クエリの解析と実行を大幅に複雑化することなく、新しい機能を追加できます。
- 指令 結果の実行と戻りに影響するフィールド、フラグメント、および操作の注釈。
- ディレクティブ引数 フィールド引数と同じ意味を持ちますが、GraphQL実行可能ファイルで処理され、フィールドハンドラー関数には渡されません。
ディスカッションに参加する
GraphQLの重要な利点は、データの取得方法を記述することができる汎用言語の存在です。 GraphQLサブスクリプションに関する継続的な議論の一環として、GraphQLについて議論するための紳士的な用語のセットができました 。
この記事では、QueryQL専用のGraphQL仕様の一部のみを取り上げました。 次の記事では、GraphQLスキーマを説明する用語を検討する場合があります。
GraphQLテクノロジーを日常業務で使用したいですか？ フロントエンド、バックエンド、オープンソースにさまざまな欠員があります！
記事の翻訳。 Sashko Stubailoによるオリジナル