GraphQLチュートリアル：Spring for GraphQLで始める

Web技術の発展に伴い、GraphQLはより柔軟で効率的なデータ取得アプローチを提供しているので、従来のREST APIの強力の代替になることが多く見られています。本文では、Springとシームレスに統合できるようGraphQLの包括的なチュートリアルを皆さんに紹介します。GraphQLの概念をわかりやすく解説した上、Spring for GraphQL利用での導入プロセスをご案内したいと思います。

また、GraphQL APIをより効率的にテストするために、直感的で使いやすいGraphQLテストツールを皆さんに紹介します。

button

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の柔軟性を組み合わせています。このプロセスには、データモデルの定義、サービス層の作成、スキーマの定義などが含まれます。また、スキーマファーストのアプローチにより、明確な設計と構造化された開発プロセスが保証されます。リゾルバによりデータ取得が簡略化され、サブスクリプションによりリアルタイム更新が可能になります。

button

使いやすいGraphQL APIテストツールおすすめ

Apidogは、強力のAPI管理ツールとして、GraphQL APIのテストをサポートしています。Apidogが提供するGraphQLエディターを使用して、クエリまたはミューテーションを作成できます。エディターは、構文の強調表示、オートコンプリート、およびエラーの強調表示をもサポートしています。

また、クエリまたはミューテーションで変数を利用する必要がある場合は、「Variable」セクションで変数を定義できるので非常に便利です。

button