{"canonical_url":"https://engineer.company/ja/glossary/graphql/","content_markdown":"# GraphQL\n\n## どのようなものか\n\nGraphQLは、API向けのクエリ言語と、そのクエリをサーバーで実行するランタイムを合わせたものです。クライアントは欲しいフィールドを正確に指定した文書を送り、サーバーは同じ形のデータを返します。仕様は、クライアントとサーバーからなるアプリケーションのための言語と実行エンジンと説明します。2012年に生まれ、2015年にオープン標準としての作業が始まり、2019年からはJoint Development Foundation傘下のGraphQL Specification Projectの成果物になったと記録しています。最新は2025年9月版です。\n\n出発点は、サービスが公開するスキーマです。名前付きのフィールドを持つ型の集合で、各フィールドにも型があります。組み込みのスカラー型は`Int`、`Float`、`String`、`Boolean`、`ID`で、UUID用など、独自のスカラーも追加できます。`!`を付けなければ、すべての型はnullを許します。`String!`は決してnullになりません。リストは角括弧で書き、`[LineItem!]!`なら、必ず存在し、nullの要素を持たないリストです。スキーマ自体にも問い合わせられます。クライアントはイントロスペクションのフィールド`__schema`と`__type`で、サービスの提供するものを尋ねられ、開発ツールやクライアントライブラリーも、これを基に作っています。\n\n操作は三種類あります。クエリは、仕様の言葉で「読み取り専用の取得」、ミューテーションは、書き込みに続く取得、サブスクリプションは、一連の出来事に応じて時間とともにデータを届ける、長く続くリクエストです。サーバーでは、各フィールドに、その値を作る、一般にリゾルバーと呼ぶ関数があります。サービスは、まずスキーマに照らして操作を検証し、その後で、選ばれたフィールドのリゾルバーだけを呼びます。ミューテーションの最上位フィールドは、並列ではなく順番に実行するため、同じリクエストの二つの書き込みが競合しません。\n\n仕様は、転送方法もシリアライズ形式も定めません。最も一般的なのはHTTPで、GraphQL APIは普通、末尾が`/graphql`の一つのURLで提供し、最も一般的な形式のJSONで答えます。クライアントは、JSON本文に`query`の文字列と、必要なら`variables`を入れてPOSTを送ります。サーバーはクエリならGETも受け付けられますが、ミューテーションは必ずPOSTです。結果は`data`、問題があれば`errors`へ入ります。この分野のGraphQL Foundationのガイドは、まだ草案のGraphQL-over-HTTP仕様に従います。\n\n## なぜ重要なのか\n\n大半のHTTP APIでは、各エンドポイントが返すものをサーバーが決めます。注文の状態と顧客名が欲しい画面は、求めたより多い、注文全体と顧客全体を受け取るか、リソースごとにリクエストし、応答を自分でつなぐ必要があります。仕様は、この二つを過剰取得と取得不足と呼びます。GraphQLは関係を逆にします。クライアントはフィールド単位で求め、そのフィールドだけを受け取ります。注文から明細、顧客へと、一つのリクエストで関係もたどれます。リクエストが、受け取るデータと同じ形だからです。\n\n型システムは、二つの面で役立ちます。リゾルバーを一つでも動かす前に、すべての操作をスキーマで検証するため、フィールド名の誤記や型の違う引数があれば、何も実行せず、操作全体を拒否します。ツールも、コードを書いているうちに同じ誤りを見つけられます。また、クライアントは選んだフィールドしか受け取らないため、フィールドを追加しても、既存のクライアントに負担をかけません。そのため、バージョン番号なしでAPIを発展させられます。古いものの隣に新しいフィールドを加え、古いものは理由付きの`@deprecated`で印を付けます。既存のクライアントを壊さないよう、有効なまま保ち、使うクライアントがなくなってから消します。\n\nこうした仕組みには実際に代償があり、その大半はHTTP本来の仕組みを外れることから生まれます。個々の対象をURLで識別せず、すべて一つのアドレスへ、普通はPOSTで送ります。一方、既定でキャッシュ可能と扱うのは、一般にGETです。REST APIが中継サーバーから自然に得るキャッシュを、意図して作り直す必要があります。データとエラーが一緒に返っても、HTTPでは成功になるため、状態コードだけでは全体を語れません。クライアントは、サーバーが見たことのないリクエストを構成します。一件で大量の仕事を求められるため、その負荷からサーバーを守るのはサービスの仕事で、GraphQLが代わりにするものではありません。フィールドごとのリゾルバーは簡単に書けますが、単純に実装すると、背後のデータベースへの問い合わせが多くなります。\n\n## 実際の活用例\n\n明細と顧客を持つ注文について、スキーマのごく一部を示します。\n\n```graphql\ntype Query {\n  order(id: ID!): Order\n}\n\ntype Order {\n  id: ID!\n  status: String!\n  items: [LineItem!]!\n  customer: Customer\n}\n\ntype LineItem {\n  name: String!\n  quantity: Int!\n}\n\ntype Customer {\n  name: String!\n}\n```\n\n注文の状態、明細、顧客名を表示する画面は、この操作を`/graphql`へPOSTの本文で送り、変数に`{\"id\": \"7421\"}`を渡します。\n\n```graphql\nquery OrderSummary($id: ID!) {\n  order(id: $id) {\n    status\n    items {\n      name\n      quantity\n    }\n    customer {\n      name\n    }\n  }\n}\n```\n\n注文と明細は解決できても、`customer`の背後のサービスが停止しているとします。応答は、作れたものをすべて含みます。失敗したフィールドはnullで、`errors`の項目が、何が問題で、文書のどこで起き、応答のどの経路に影響するかを示します。8行目の5列目が`customer`です。\n\n```json\n{\n  \"data\": {\n    \"order\": {\n      \"status\": \"open\",\n      \"items\": [{ \"name\": \"notebook\", \"quantity\": 2 }],\n      \"customer\": null\n    }\n  },\n  \"errors\": [\n    {\n      \"message\": \"Customer service unavailable\",\n      \"locations\": [{ \"line\": 8, \"column\": 5 }],\n      \"path\": [\"order\", \"customer\"]\n    }\n  ]\n}\n```\n\n`customer`はnullを許す宣言なので、影響はそこで止まります。もし`Customer!`なら、エラーは親へ伝わり、注文全体がnullで返ります。また、`data`はnullではないため、エラーがあってもサーバーは2xxで答えます。HTTPには部分的な成功の状態コードがないためです。状態コードしか見ないクライアントは、これを完全な応答と扱います。\n\n反対に、応答の形をすべてサーバーが決める設計を、このサイトの事例の一つで作りました。[PostgresからAPIへJSONをそのまま通す実装](/ja/portfolio/designed-a-json-passthrough-from-postgres-to-api/)では、PostgreSQLの関数が応答全体をJSONに組み立て、Goのハンドラーは変更せず転送します。そのため、関数の戻すものを変えれば、ハンドラーを一行も編集せずに、クライアントの受け取るものが変わります。そこではフロントエンドが、データベースの与える形へ直接依存します。GraphQLではクライアントがフィールドを指定し、サーバーは、スキーマが許す、どの組み合わせでも解決できる必要があります。\n\n## 問題が起きるところ\n\n**一つのフィールドで、データベースを千回呼びます。** リゾルバーはフィールドごとの小さい関数で、単純な実装では、オブジェクトを一つずつ処理します。各注文の顧客も含む一覧なら、一覧用に一回、各注文にさらに一回のデータベース呼び出しが必要です。GraphQL FoundationのガイドはN+1問題と呼び、まとめて処理する方法を示します。短い時間枠に要求された読み込みを集め、FacebookのDataLoaderなどで、一つのリクエストとしてデータベースへ送ります。\n\n**一つのリクエストが、すべてを求めます。** 操作を書くのはクライアントなので、一文書で友人の友人を何層も深くたどったり、重いフィールドを百個の別名で繰り返したり、多くの操作を一つのリクエストへ詰めたりできます。どれも有効なGraphQLで、どれもサーバーを占有しかねません。防御はサービス側で行います。リストのフィールドをページ分割し、実行前に深さや幅の上限を超える操作を拒否し、別名の数とバッチの大きさを制限します。さらに細かくするなら、各フィールドへ重みを与え、見積もった負荷が予算を超える操作を拒否します。クエリ複雑度解析と呼ぶ手法ですが、仕様自体は、その規則を定めません。自社のクライアントだけに提供するAPIなら、事前に保存してハッシュで探す操作だけを実行する、信頼済み文書の方式で、さらに制限できます。\n\n**200 OKが失敗を隠します。** 上の例のように、エラーを含む応答も2xxになり得ます。古いメディア型`application/json`について、ガイドはさらに、正しいリクエストを実行できなかった場合でも2xxを勧め、一部の古いサーバーは、検証エラーでも2xxを返します。クライアントと周囲の監視は、状態だけでなく`errors`を読む必要があります。新しいメディア型`application/graphql-response+json`なら、正しいリクエストが実行できない場合は4xxか5xxとなり、状態が再び意味を持ちます。クライアントは`Accept`ヘッダーで、この形式を求めるべきです。\n\n**キャッシュが機能しなくなります。** どの操作も同じURLへのPOSTなので、CDNを含む、クライアントとサーバーの間のキャッシュからは、一つのアドレスと、既定ではキャッシュしないメソッドに見えます。クエリをGETで送れば役立ちますが、長い文書はブラウザーやCDNが許すURL長を超える場合があります。永続化クエリは両方を解決します。クライアントはハッシュを送り、サーバーは文書全体を引き出してから、検証、実行します。HTTPで応答をキャッシュするなら、機微な情報を含む応答はプライベートキャッシュに限って保存するか、まったくキャッシュしない必要があります。\n\n**フィールドが消えます。** クライアントは一つずつ選ぶため、フィールドの削除や改名は、それを選ぶすべてのクライアントを壊します。軽い影響では済みません。存在しないフィールドを指定した操作は、全体が検証に失敗し、データは何も返りません。仕様が非推奨のフィールドも有効に保つのは、既存のクライアントを壊さないためです。まず代わりを追加し、新しいものを示す理由を付けて、古いものを`@deprecated`にします。どのクライアントも選ばなくなってから、古いフィールドを削除します。\n\n## 参考資料\n\n- [GraphQL仕様の各版](https://spec.graphql.org/) — 2015年7月から2025年9月版までの全版と、作業中の草案です。言語、型システム、検証、実行、エラーを扱います。\n- [HTTPでの提供](https://graphql.org/learn/serving-over-http/) — 単一エンドポイント、POSTとGET、二つの応答メディア型、それぞれの状態コードの規則です。\n- [性能](https://graphql.org/learn/performance/) — クエリのGET送信、永続化クエリ、N+1問題、バッチ処理です。\n- [セキュリティ](https://graphql.org/learn/security/) — 信頼済み文書、深さ、幅、バッチの制限、クエリ複雑度解析、および本番でのイントロスペクションとエラーの詳細です。\n\n\u003chttps://engineer.company/ja/glossary/graphql/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"クライアントが受け取るフィールドを選ぶGraphQLを解説します。型とリゾルバーの仕組み、単一エンドポイントがキャッシュや状態コードに与える影響、APIで起きる五つの問題と対処も説明します。","formats":{"gemtext":"https://engineer.company/ja/glossary/graphql/index.gmi","gopher":"https://engineer.company/ja/glossary/graphql/gophermap","html":"https://engineer.company/ja/glossary/graphql/","json":"https://engineer.company/ja/glossary/graphql/index.json","markdown":"https://engineer.company/ja/glossary/graphql/index.md","pdf":"https://engineer.company/ja/glossary/graphql/index.pdf"},"kind":"page","language":"ja","title":"GraphQLとは？","url":"https://engineer.company/ja/glossary/graphql/","version":1}