新卒エンジニアが実践した「小さく作る」GraphQL学習プロセス

1.はじめに
2.なぜ作ろうと思ったか
3.本記事で扱う技術スタック
4.やったこと
5.学んだこと
- ① 自分の理解できているところ/できていないところがはっきりした
- ②「作ってみる」ことへの心理的ハードルが下がった
6.今後の展望

1.はじめに

こんにちは。
テクノロジー統括プロダクト開発第二部の湯川です。
2025年に新卒入社しました。
実務でGraphQL APIの実装に携わることになり、自己学習の一環として、小さなAPIを自分で作ってみました。
本記事の対象者は下記です。

新卒エンジニアで実務の既存コードを難しく感じている方
自己学習の進め方に迷っている方

自分が取り組んだこと、この経験を通して学んだことを共有するので、少し前の自分と同じような状況にいる方の参考になれば嬉しいです。

2.なぜ作ろうと思ったか

新卒研修でC#の基礎を一通り学び、現チームに配属された後、GraphQL APIの実装に携わることになりました。
実装に入るにあたり、まずは既存コードを読み、GraphQL APIの構成や処理の流れを理解しようと試みました。
しかし、既存コードではさまざまなライブラリや設計手法が活用されており、基礎学習を終えたばかりの自分にとっては、コードの意図や処理の流れを掴むのはまだ難しい状態でした。
特に、

リクエストがどこから入り
どのクラスを通って
どうやってレスポンスが返るのか

といったAPIの基本的な流れを、既存コードから追うのが難しく感じていました。
そこで、いきなり全体を理解しようとするのではなく、GraphQL APIの最小単位を自分の手で作ることで、リクエストからレスポンスまでの流れを一度シンプルな形で掴みたいと考え、理解を深めるための第一歩として、最小構成のGraphQL APIを作ってみることにしました。

3.本記事で扱う技術スタック

本記事では、以下の技術を使用して、GraphQL APIの実装を行いました。

言語：C#
フレームワーク：ASP.NET Core
API方式：GraphQL
GraphQLライブラリ：Hot Chocolate

今回作ったのは、「本をタイトルで検索できる、シンプルなAPI」です。
本のタイトルを対象に、指定した文字列を含む本を検索できる、最小構成のAPIを作りました。
なお、本記事ではソースコードは必要な部分のみ記載しています。
また、今回の実装はリクエストからレスポンスまでの流れを理解することが目的のため、エラーハンドリングなどについては考慮しておらず、最低限動くレベルのコードになっています。

参考にしたページ：
chillicream.com

4.やったこと

Step1. 処理を持たないGraphQL APIの起動確認

まず、GraphQL APIが起動するだけの状態を作りました。
「とりあえず中身は空でいいから、まずはビルドを通して、エラーなく起動するところまでやってみよう」
と思い、ロジックやデータ定義は後回しにして、最低限のコードだけを書きました。

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddGraphQLServer()
    .AddQueryType<Query>();

var app = builder.Build();

app.MapGraphQL();
app.RunWithGraphQLCommandsAsync(args);

public class Query { }

実行し、下記URLにアクセスすると、GraphQLの実行画面(Nitro)が表示されました。
http://localhost:xxxx/graphql
(xxxxはアプリケーション起動時に割り当てられたポート番号を表しています。)

ここまでで、GraphQL APIが起動している状態が確認できました。

Step2. 本を表すクラスを作る

次に、このAPIで扱うデータを定義しました。
今回はシンプルに、idとタイトルのみを持つ「本」を表すクラスを用意しました。

public class Book
{
    public int Id { get; set; }
    public string Title { get; set; } = string.Empty;
}

Step3. 本の一覧を返すメソッドを作る

続いて、固定値のデータを用意し、Queryクラスに本の一覧を返すメソッドを追加しました。

public class Query
{
    // 固定値のデータ
    private static readonly List<Book> _books = new()
    {
        new Book { Id = 1, Title = "GraphQL入門" },
        new Book { Id = 2, Title = "C#徹底解説" },
        new Book { Id = 3, Title = "Hot Chocolate実践" },
    };

    // 本の一覧を返すメソッド
    public List<Book> GetBooks()
    {
        return _books;
    }
}

この状態でGraphQLの実行画面から、次のクエリを実行してみました。

query {
  books {
    id
    title
  }
}

すると、次のようなデータが返ってきました。

{
  "data": {
    "books": [
      { "id": 1, "title": "GraphQL入門" },
      { "id": 2, "title": "C#徹底解説" },
      { "id": 3, "title": "HotChocolate実践" }
    ]
  }
}

「自分で書いたコードがGraphQL APIとして動いている」という感覚を、ここで初めて実感できました。

Step4. 検索条件を表すクラスを作る

次に、APIが検索条件を受け取れるように、検索条件を表すクラスを定義しました。

public class BookSearchInput
{
    public string? FreeWord { get; set; }
}

Step5. 検索条件と一致した本の一覧を返すメソッドを作る

Step3で作成したメソッドの引数に検索条件を追加し、検索条件と一致したデータを取得するロジックをメソッド内に追加しました。

public class Query
{
    private static readonly List<Book> _books = new()
    {
        new Book { Id = 1, Title = "GraphQL入門" },
        new Book { Id = 2, Title = "C#徹底解説" },
        new Book { Id = 3, Title = "HotChocolate実践" },
    };

    public List<Book> GetBooks(BookSearchInput? bookSearchInput)
    {
        var books = _books;

        if (bookSearchInput != null)
        {
            books = books
            .Where(book => book.Title.Contains(bookSearchInput.FreeWord))
            .ToList();
        }
        return books;
    }
}

このときは、
「検索条件を受け取ったあと、どうやって一覧を絞り込めばいいんだろう？」
と試行錯誤しながら進めていました。
最初は、
「コードが多少汚くてもいいから、とりあえず書いてみよう」
と割り切って、過去に学習した内容を振り返りながら手を動かしました。
コードを書き進めるなかで、
「自分が学習してきた内容で、こうした検索処理まで書けるんだ」
という実感が湧いてきました。

クエリに検索条件を加えて、GraphQLの実行画面から実行してみました。

query {
  books(bookSearchInput: { freeWord: "GraphQL" }) {
    id
    title
  }
}

すると、検索条件に合致したデータが返ってきました。

{
  "data": {
    "books": [
      { "id": 1, "title": "GraphQL入門" },
    ]
  }
}

なんとか本をタイトルで検索ができるAPIができました。
実務のコードでは見えにくかった
「リクエスト → 処理 → レスポンス」
というAPIの基本的な流れを、最小構成の中で初めて理解できた感覚がありました。

Step6. 既存コードと照らし合わせる

Step5までで、リクエストからレスポンスまでの流れを一度シンプルな形で掴むことができました。
次に取り組んだのは、今回作った最小構成のAPIとチームで扱っている既存コードを照らし合わせることです。

「この部分は、既存コードのどこに対応しているのか」
「この処理は、既存コードではどんな構成になっているのか」

そんなふうに一つずつ対応関係を見ながら、流れを追っていきました。
その上で、

検索条件を増やしてみる
固定値のデータを、データベースから取得する形に置き換えてみる
既存コードで使われているライブラリを一つずつ組み込んでみる

といった形で、小さなAPIを少しずつアップデートしていきました。
その結果、既存コードも「なんとなく読める」状態から、「ここはこの役割を持っている」と流れを意識しながら読めるようになり、少しずつですがAPI全体の解像度が上がってきたと感じています。

5.学んだこと

① 自分の理解できているところ/できていないところがはっきりした

自分が理解できる範囲で何かを作ることで、

今の知識で何ができるのか
逆に、何がまだ分からないのか

が明確になりました。
現状が見えると、「次に何を学べばいいか」も自然と浮かんできました。

②「作ってみる」ことへの心理的ハードルが下がった

以前の自分は「APIを作る」と聞くだけで身構えていました。
でも今回のように、小さく、まずは動くところまでだけ作ってみると、「これくらいなら自分でもできる」と思えるようになりました。
完璧なものを目指すよりも、まずは動くものを作ってみる。
その一歩を踏み出せたことは、自分にとって大きな変化でした。