新人と先輩の会話形式で理解しよう

新人

「先輩、最近よく聞くGraphQLスキーマって何なんですか？API開発で使うと便利って聞いたんですが、まだよく分かっていなくて…。」

先輩

「GraphQLスキーマは、GraphQLで作るAPIの設計図みたいなものなんだ。リクエストできるデータの種類や構造を、型システムを使って定義するんだよ。」

新人

「型システムって聞くと難しそうですが、Javaのクラスみたいなものだと考えればいいんですか？」

先輩

「その考え方で大丈夫だよ。GraphQLスキーマでは、取得できるデータの型や関連性を定義するから、Javaのクラスを思い浮かべると分かりやすいと思う。」

新人

「なるほど。Spring Boot GraphQLでは、このスキーマをどこに置けばいいんですか？」

先輩

「Spring BootでGraphQLを使う場合は、プロジェクト内の特定の場所に.graphqlsファイルを配置するんだ。pleiadesでGradleプロジェクトを作成して、依存関係を追加すれば簡単に始められるよ。」

1. GraphQLスキーマとは？

GraphQLスキーマとは、GraphQLで構築するAPI開発の基本となる「設計図」のことです。スキーマには、クライアントがリクエストできるデータの種類、データ同士の関係、そしてクエリやミューテーションの形が定義されます。これにより、APIの利用者は「どのようなデータを取得できるのか」を明確に理解できるようになります。

例えば、ユーザー情報を扱うAPIを考えてみましょう。スキーマでUserという型を定義しておくと、クライアントはその型を通じて名前やメールアドレスといった情報を取得することができます。GraphQLスキーマは、APIとクライアントの間で共通のルールを作る重要な役割を果たしているのです。

2. GraphQLスキーマと型システムの役割

GraphQLの特徴は、型システムを利用して明確にデータを定義することです。Javaのクラスと似ていて、文字列ならString型、数値ならInt型といった具合に、データの形式をあらかじめ決めておきます。

この型システムのおかげで、クライアントはAPIに対して安心してリクエストを送ることができます。もし間違った型でリクエストをしてしまった場合には、GraphQLの仕組みがエラーを返してくれるため、バグを早い段階で防ぐことが可能です。

以下のようなスキーマ定義をイメージしてみましょう。


type User {
    id: ID!
    name: String!
    email: String!
}
type Query {
    users: [User]
}

この例では、User型を定義し、Query型を通してユーザーの一覧を取得できるようにしています。型システムを明示することで、API利用者にとって分かりやすく、開発者にとっても保守しやすい仕組みが実現できます。

3. Spring BootにおけるGraphQLスキーマの配置場所

Spring Boot GraphQLを使う場合、スキーマファイルはプロジェクトの特定ディレクトリに配置します。pleiadesでGradleプロジェクトを作成した場合、次のような構成になります。


src
 └── main
     └── resources
         └── graphql
             └── schema.graphqls

このschema.graphqlsファイルに、先ほどのUserやQueryの定義を記述していきます。Spring Bootは、このディレクトリを自動的に読み込んでくれるため、特別な設定を追加しなくてもGraphQL APIを利用できます。

さらに、コントローラ側では必ず@Controllerを使用して処理を定義します。例えば、ユーザー情報を返すクラスを以下のように書けます。


@Controller
public class UserController {
    @QueryMapping
    public List<User> users() {
        List<User> list = new ArrayList<>();
        list.add(new User(1, "Taro", "taro@example.com"));
        list.add(new User(2, "Hanako", "hanako@example.com"));
        return list;
    }
}

このように、GraphQLスキーマとSpring Bootのコントローラを組み合わせることで、強力で柔軟なAPI開発が可能になります。pleiadesの環境とGradleを利用することで、初心者でも簡単に設定できる点も大きなメリットです。

4. 基本的なGraphQLスキーマ定義の例

ここからは、初心者向けに分かりやすくGraphQLスキーマ定義の基本的な書き方を解説します。GraphQLスキーマ定義は、API開発でどのようなデータを取得できるのかを明示する役割があります。Spring Boot GraphQLの環境では、.graphqlsファイルにスキーマを記述します。

例えば、ユーザー情報と記事情報を扱うAPIを考えてみましょう。この場合、User型とArticle型を定義しておくと、クライアント側はユーザーと記事の両方をリクエストできるようになります。


type User {
    id: ID!
    name: String!
    email: String!
}

type Article {
    id: ID!
    title: String!
    content: String!
    author: User!
}

type Query {
    users: [User]
    articles: [Article]
}

このスキーマ定義では、ユーザーと記事の二つの型を用意し、Query型を通して一覧を取得できるようにしています。GraphQLスキーマ定義は、API開発を進めるうえでとても重要な役割を果たします。

5. Query型を使ったデータ取得の定義方法

次に、GraphQLクエリを使ってデータを取得する方法について説明します。GraphQLでは、Query型に定義されたフィールドを利用して、必要なデータを指定して取得することができます。Spring Boot GraphQLでは、クライアント側が送信するクエリとスキーマで定義された内容が一致していることが前提になります。

例えば、ユーザー情報だけを取得したい場合には、次のようなGraphQLクエリを送信します。


query {
    users {
        id
        name
        email
    }
}

このクエリを実行すると、usersのリストが返され、各ユーザーのid、name、emailが取得できます。GraphQLクエリは、欲しいフィールドだけを明示的に指定できる点がREST APIとの大きな違いです。これにより、クライアントは効率的に必要な情報だけを取得でき、通信の無駄を減らせます。

さらに、記事とその著者情報を同時に取得したい場合は次のように書きます。


query {
    articles {
        id
        title
        content
        author {
            name
            email
        }
    }
}

このように、Query型を利用することで複数の型を組み合わせたデータを簡単に取得できます。Spring Boot API開発におけるGraphQLクエリは、柔軟で拡張性が高い仕組みになっているため、初心者でも段階的に学ぶことが可能です。

6. Spring BootでのGraphQLスキーマファイルの作成手順

ここでは、Spring BootでGraphQLスキーマファイルを作成する具体的な手順を解説します。開発環境はpleiadesとGradleを前提としています。

手順1: プロジェクトを作成する

まず、pleiadesを使って新しいGradleプロジェクトを作成します。Spring Initializrを利用してSpring Bootプロジェクトを生成し、必要な依存関係としてspring-boot-starter-graphqlを追加します。依存関係はpleiadesのチェックボックスで選択できるため、初心者でも迷わず設定できます。

手順2: スキーマファイルの配置ディレクトリを用意する

プロジェクト構成の中に、次のようにresources/graphqlディレクトリを作成します。この場所にGraphQLスキーマ定義ファイルを配置します。


src
 └── main
     └── resources
         └── graphql
             └── schema.graphqls

手順3: スキーマファイルを作成する

先ほどの定義例を参考に、schema.graphqlsファイルを作成して保存します。


type User {
    id: ID!
    name: String!
    email: String!
}

type Query {
    users: [User]
}

手順4: コントローラを作成する

Spring BootでGraphQLを扱う際には、必ず@Controllerを使ってクエリの処理を記述します。以下は、ユーザー情報を返すコントローラの例です。


@Controller
public class UserController {

    @QueryMapping
    public List<User> users() {
        List<User> list = new ArrayList<>();
        list.add(new User(1, "Taro", "taro@example.com"));
        list.add(new User(2, "Hanako", "hanako@example.com"));
        return list;
    }
}

このように、スキーマ定義とコントローラを組み合わせることで、GraphQLクエリに対応したAPIを構築できます。Spring Boot API開発では、スキーマファイルとコントローラの連携を正しく行うことが成功のポイントです。初心者はまず小さなスキーマ定義から始め、徐々に複雑な構造に拡張していくと理解しやすいでしょう。

7. @Controllerを利用したクエリ処理の実装例

ここからは、Spring Boot GraphQLでの実際の実装例を紹介します。GraphQL 実装例を通じて、どのようにクエリ処理が行われるのかを具体的に学びましょう。必ず@Controllerを利用してクラスを作成し、クエリ処理を定義することが重要です。

以下の例では、ユーザー情報をGraphQLクエリから取得できるようにするためのクラスを実装しています。


@Controller
public class UserController {

    private final List<User> userList = new ArrayList<>(
        List.of(
            new User(1, "Taro", "taro@example.com"),
            new User(2, "Hanako", "hanako@example.com")
        )
    );

    @QueryMapping
    public List<User> users() {
        return userList;
    }

    @QueryMapping
    public User userById(@Argument int id) {
        return userList.stream()
                .filter(u -> u.getId() == id)
                .findFirst()
                .orElse(null);
    }
}

この例では、全てのユーザーを返すusersと、特定のIDに一致するユーザーを返すuserByIdを定義しています。GraphQLスキーマに記述した内容と対応しているため、クライアントから送信されるGraphQLクエリを処理できるようになります。

8. 実際にGraphQLクエリを送信してデータを取得する流れ

GraphQL 実装例を理解したら、次に実際にクエリを送信してデータを取得する流れを確認しましょう。Spring Boot GraphQLでは、アプリケーションを起動した後に/graphqlエンドポイントにリクエストを送ることでクエリを実行できます。

例えば、すべてのユーザーを取得する場合、以下のようなGraphQLクエリを送信します。


query {
    users {
        id
        name
        email
    }
}

このリクエストを送信すると、レスポンスは次のように返されます。


{
  "data": {
    "users": [
      {
        "id": 1,
        "name": "Taro",
        "email": "taro@example.com"
      },
      {
        "id": 2,
        "name": "Hanako",
        "email": "hanako@example.com"
      }
    ]
  }
}

また、特定のユーザーだけを取得したい場合には次のようなGraphQLクエリを送ります。


query {
    userById(id: 1) {
        id
        name
        email
    }
}

すると、以下のように対象ユーザーのデータが返ってきます。


{
  "data": {
    "userById": {
      "id": 1,
      "name": "Taro",
      "email": "taro@example.com"
    }
  }
}

このようにGraphQLクエリを送信すると、必要なフィールドだけを効率的に取得できます。Spring Boot GraphQL クエリを実際に試すことで、API開発の流れを理解しやすくなります。

9. GraphQLを学習する上でのおすすめの方法

最後に、GraphQLを学習する上でのおすすめの方法を紹介します。初心者にとってGraphQLは新しい概念が多く、REST APIと比べて学習の入り口で混乱しやすい部分もあります。そのため、実際に手を動かしながら理解を深めることが最も効果的です。

おすすめのステップは次のとおりです。

1. 小さなスキーマ定義から始める

まずは簡単な型とクエリを定義して、少しずつ拡張していきましょう。例えばユーザー型だけを定義して、名前とメールアドレスを返すような簡単なAPIを作るのが効果的です。

2. pleiadesでGradleプロジェクトを繰り返し作成する

環境構築の経験を積むために、複数回プロジェクトを作成して依存関係を追加する練習をすると良いです。Spring Boot API開発の流れを体に覚えさせることができます。

3. 実際にGraphQLクエリを送信して試す

GraphQLクエリを自分で書いて、どのようなレスポンスが返ってくるのかを確認すると理解が深まります。フィールドを増やしたり減らしたりして、柔軟にデータを取得できるGraphQLの強みを体感しましょう。

4. ドキュメントとチュートリアルを読む

公式ドキュメントやSpring Boot GraphQLの解説記事を読みながら、自分のコードと照らし合わせることも大切です。SEOに強い学習記事やサンプルコードを活用することで、効率的に学習を進められます。

このような学習方法を繰り返すことで、GraphQL 実装例を自分で作れるようになり、Spring Boot GraphQL クエリを活用した実践的なAPI開発のスキルが身につきます。初心者でも少しずつ進めていけば、確実に理解できるようになるでしょう。

GraphQLスキーマ入門｜Spring Bootで学ぶAPI開発の基本