GraphQLチュートリアル：Spring for GraphQLで始める
本文では、包括的なGraphQLのチュートリアルを皆さんに紹介します。GraphQLの概念を詳しく解説した上、Spring for GraphQLを使って始める方法を解説します。
Web技術の発展に伴い、GraphQLはより柔軟で効率的なデータ取得アプローチを提供しているので、従来のREST APIの強力の代替になることが多く見られています。本文では、Springとシームレスに統合できるようGraphQLの包括的なチュートリアルを皆さんに紹介します。GraphQLの概念をわかりやすく解説した上、Spring for GraphQL利用での導入プロセスをご案内したいと思います。
shimizu chioka
また、GraphQL APIをより効率的にテストするために、直感的で使いやすいGraphQLテストツールを皆さんに紹介します。
Spring for GraphQLとは
Spring for GraphQLは、Spring FrameworkにGraphQLのサポートを追加するライブラリです。開発者は、それを使ってGraphQLベースのAPIをシームレスに構築できます。Spring for GraphQLはSpring Bootの開発のしやすさとGraphQLの柔軟性・効率性を組み合わせているので、近代的なAPI開発に理想的な選択肢といえます。
Spring for GraphQLの主な機能
Spring for GraphQLはGraphQLの実装をシンプルにし、SpringアプリケーションにGraphQLを導入しやすくする目的で開発されたライブラリとして、主に次ような機能を提供しています。
- GraphQLスキーマの定義が容易になります。アノテーションを使ってGraphQLオブジェクトタイプとクエリを定義できます。
- リゾルバメソッドの実装が簡単になります。コントローラーのメソッドに@Queryアノテーションを付けるだけで、GraphQLクエリに対するリゾルバとなります。
- GraphQLスキーマはスキーマファーストでもコードファーストでも定義できます。スキーマ定義ファイルとアノテーションの併用が可能です。
- GraphiQLインタフェースが提供されており、開発時のスキーマ確認やクエリテストがし易くなります。
- 認証や権限管理もSpring Securityとの連携が可能です。
- GraphQLサブスクリプション(リアルタイム更新)にも対応しています。
- DataLoaderによる呼び出し最適化など、パフォーマンス向上のための機能もサポートしています。
GraphQLでSpring Bootプロジェクト構築に要する環境設定
GraphQLとSpringの使用を開始する前に、さまざまな事前設定が必要になります。GraphQLを使用してSpring Bootプロジェクトを構築するために、必要な環境の準備ができたことを確認する必要があります。それでは、次は環境設定の手順を皆さんに紹介したいと思います。
前提条件
Spring for GraphQLを使用するための前提条件は以下の通りです:
- JDK 17: システムにJDK 17をインストールする必要があります。OracleやOpenJDKからダウンロードできます。
- Spring Bootの基礎知識: Spring Bootの基本を理解している必要があります。GraphQLを構築する際に役立ちます。
Spring Bootプロジェクトを作成
まずはSpring Bootプロジェクトの始点となるSpring Initializr（start.spring.io）にアクセスして次のような操作を行なってください。
まず、プロジェクト名の指定し、グループ名を逆にしたドメインフォーマット(例: com.example)を定義し、アプリのJavaコード用のパッケージ名を設計するなど、プロジェクトの詳細セットアップする必要があります。必要に応じて、説明やバージョンも含めることができます。
次に、必要な依存関係を追加してください。Dependenciesセクションで、SpringによるWebアプリケーションの作成を可能にするために「Spring Web」を選択してください。同様に、GraphQL関連の機能を有効にするために「Spring GraphQL」をチェックしてください。プロジェクトを設定し、依存関係を選択したら、「Generate」ボタンをクリックして進んでください。
IDEへのプロジェクトのインポート
まず、ZIPファイルの内容を抽出して、その内容にアクセスしてください。次に、IntelliJ IDEAなどの統合開発環境(IDE)を開いてください。その後、前に抽出したプロジェクトをそこにインポートしてください。
ここで環境のセットアップが完了し、Spring Bootプロジェクトを作成しました。それに、GraphQLのAPIも作成されました。
GraphQLでSpring Bootプロジェクトを構築する方法
次は、GraphQLがどのようにデータ検索と管理を強化するかを解説するために、コーヒーショップの管理に関するGraphQL APIを簡単なサンプルにしていきたいと思います。
GraphQL APIのサンプル
コーヒーショップのメニューと注文を管理するAPIを開発する想定です。 関連の機能を実現するために、コーヒーショップの商品、顧客の基本情報などのデータモデルを定義する必要があります。このGraphQL APIは、これらのデータを扱うためのサービスになります。
GraphQLのデータモデルの定義
まず、CoffeeとSizeの2つのシンプルなデータモデルを作成します。 これらのモデルはJavaクラスとして実装され、関連情報の属性を持ちます。 2つのクラスを2つのファイルに作成する必要があります。各クラスには、属性としてコンストラクタ、ゲッター、セッターを追加する必要があります。
public class Coffee {
private int id;
private String name;
private Size size;
// Constructors, getters, setters
}
public class Size {
private int id;
private String name;
// Constructors, getters, setters
}
これらのクラスを作成して追加すると、それらがSpring Bootプロジェクト内の適切なパッケージ内に配置されていることを確認する必要があります。 パッケージ構成は、Spring Initializrでプロジェクトを生成する際に指定したパッケージ名を反映させるべきです。
Coffee.javaクラスにセッター、ゲッター、コンストラクタを追加する方法は以下のようになります。
データ管理をセットアップ
データ管理を設定するには、以下のようにCoffeeServiceクラスを作成してインメモリデータリポジトリとして機能させ、コーヒーデータを管理できるようにします。このような機能を実現するために、次のようなコードでコーヒーアイテムのサンプルを追加してください。
import java.util.ArrayList;
import java.util.List;
@Component
public class CoffeeService {
private final List<Coffee> coffees = new ArrayList<>();
@PostConstruct
public void init() {
Size smallSize = new Size(1, "Small");
Size mediumSize = new Size(2, "Medium");
Size largeSize = new Size(3, "Large");
coffees.add(new Coffee(1, "Espresso", smallSize));
coffees.add(new Coffee(2, "Latte", mediumSize));
coffees.add(new Coffee(3, "Cappuccino", largeSize));
// サンプルのCoffeeデータを初期化
}
public List<Coffee> getAllCoffees() {
return coffees;
}
public Coffee getCoffeeById(int id) {
return coffees.stream()
.filter(coffee -> coffee.getId() == id)
.findFirst()
.orElse(null);
// IDに基づいてCoffeeを取得
}
}
CoffeeServiceクラスは、ストレージおよび検索システムとして機能し、コーヒー関連のデータを管理します。作成時にサンプルのコーヒーデータを初期化し、すべてのコーヒーを取得するメソッドや、IDに基づいて特定のコーヒーを取得するメソッドを提供します。この抽象化により、データアクセスと操作が合理化され、GraphQLスキーマ内でのデータとのインタラクションの準備が整えられます。
GraphQL Schemaを作成する方法
次の画像のように、src/main/resourcesフォルダで、schema.graphqlsというファイルを作成すると、Schema定義言語を使って、GraphQLのSchemaを定義ます。
type Query {
getAllCoffees: [Coffee!]!
getCoffeeById(id: Int!): Coffee
}
type Coffee {
id: Int!
name: String!
size: Size!
}
type Size {
id: Int!
name: String!
}
データフェッチャーの作成
データフェッチャーを作成するには、以下のコードによって実現できます：
import graphql.GraphQL;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class GraphQLController {
@Autowired
private GraphQL graphQL;
@PostMapping("/graphql")
public Map<String, Object> executeQuery(@RequestBody String query) {
ExecutionResult executionResult = graphQL.execute(query);
return executionResult.toSpecification();
}
}
@Componentアノテーションを付けることでSpringに管理されるCoffeeDataFetcherクラスを定義します。getAllCoffees() はCoffeeServiceを利用して全コーヒーデータを取得します。getCoffeeById() はクエリの引数からIDを取り出し、そのIDのコーヒーデータを取得します。
このようにDataFetcherインタフェースを実装することで、GraphQLのクエリに対応したデータ取得ロジックをカプセル化できます。スキーマ定義とデータフェッチャーを合わせることで、GraphQL APIのbackendが完成します。
GraphQLコントローラーの作成
GraphQLコントローラーを作成するには次のようにできます。
import graphql.GraphQL;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class GraphQLController {
@Autowired
private GraphQL graphQL;
@PostMapping("/graphql")
public Map<String, Object> executeQuery(@RequestBody String query) {
ExecutionResult executionResult = graphQL.execute(query);
return executionResult.toSpecification();
}
}
このコントローラーは、入力されたGraphQLクエリを処理し、定義したGraphQLスキーマと対話します。
/graphqlというRESTfulなエンドポイントを提供し、リクエストボディにGraphQLクエリを含むPOSTリクエストを受け付けます。
コントローラーはGraphQLインスタンスを使用してクエリを実行し、実行結果をMapとして返します。Spring GraphQLは、GraphQLクエリ言語を使用して効率的なAPIを構築できる強力なフレームワークです。従来のREST APIとは異なり、クライアントは1つのリクエストで必要なデータを正確に指定できるため、データの過剰や不足が軽減されます。
Spring for GraphQLはSpringエコシステムの強みを活かし、Spring BootのシンプルさとGraphQLの柔軟性を組み合わせています。このプロセスには、データモデルの定義、サービス層の作成、スキーマの定義などが含まれます。また、スキーマファーストのアプローチにより、明確な設計と構造化された開発プロセスが保証されます。リゾルバによりデータ取得が簡略化され、サブスクリプションによりリアルタイム更新が可能になります。
使いやすいGraphQL APIテストツールおすすめ
Apidogは、強力のAPI管理ツールとして、GraphQL APIのテストをサポートしています。Apidogが提供するGraphQLエディターを使用して、クエリまたはミューテーションを作成できます。エディターは、構文の強調表示、オートコンプリート、およびエラーの強調表示をもサポートしています。
また、クエリまたはミューテーションで変数を利用する必要がある場合は、「Variable」セクションで変数を定義できるので非常に便利です。
