GoでGraphQLサーバを作る

ハンズオン形式で、GoでGraphQLサーバを構築するための基礎知識を紹介します。
完成版は、[GitHub](https://github.com/KamikazeZirou/gql-example)に上げてあります。

## GraphQLの概要
### GraphQLとは

GraphQLは、Facebookが作ったAPI形式です。[公式ページ](https://graphql.org/learn/)から引用します。

`
GraphQLは、APIのためのクエリ言語であり、データに対して定義した型システムを使ってクエリを実行するためのサーバーサイドランタイムです。
`

### GraphQLの使い方

以下のGraphQLのスキーマがあるとします。

```graphql
type Query {
  me: User
}

type User {
  id: ID
  name: String
  profileUrl: String
}
```

次のようなGraphQLクエリを実行することができます。クエリは、HTTPのPOSTかGETリクエストです。生のHTTPリクエストではなく、AplloやRelayといったGraphQLクライアントライブラリを使ってリクエストすることが多いです。

**クエリ**

```graphql
{
  me {
    id
    name
    profileUrl
  }
}
```

**レスポンス**

```
{
  "me": {
    "id": "user:123456"
    "name": "田中太郎"
    "profileUrl": "https://xxx.yyy.zzz/..."
  }
}
```

GraphQLの特徴として、レスポンスのフィールドを絞ることもできます。

**レスポンスのフィールドを絞ったクエリ**

```graphql
{
  me {
    name
  }
}
```

### GraphQLの良いところ

1. レスポンスのフィールドが指定できるので、オーバフェッチ/アンダーフェッチを回避できます
1. 型があります
1. ApolloなどのGraphQLクライアントは、クエリの結果をいい感じにローカルキャッシュしてくれます
1. 1リクエストに複数のクエリや更新操作を含めることができます

個人的には、レスポンスフィールドを指定できる点が良いです。モバイルアプリとWeb Frontがある状況で、それぞれにAPIを用意したり、独自のフィールド指定の仕組みを作ったりしなくても、両方のユースケースで過不足ないレスポンスを返すことができます。

## GoでGraphQLサーバを作る

ここからは、GoのGraphQLサーバを作っていきます。

### 使うライブラリ：gqlgen

[gqlgen](https://github.com/99designs/gqlgen)というライブラリを使います。

GraphQLサーバを実現するライブラリは、コードファーストとスキーマファーストに大別されます。gqlgenはスキーマファーストに分類されます。gqlgenを使う理由は、GoのスキーマファーストのGraphQLライブラリの中で人気だからです。後は、仕様から考えるのが自分の性にあっているからです。

gqlgenを使ったGraphQLの開発の流れは以下のようになります。

1. GraphQLのスキーマを定義
1. スキーマからGoとしての型定義やリゾルバの雛形を生成する
    - リゾルバはスキーマとデータソースを結びつける役割を持ちます。雛形は
1. 生成したリゾルバの雛形を実装する

### GraphQLサーバを動かす

まず、[gqlgenのGetting Started](https://gqlgen.com/getting-started/)の手順を実施してください。以降の説明は、Getting Startedを実施した前提です。

## N+1問題とその対処

gqlgenのGetting Startedを完了すると、Todoの一覧を取得する以下のクエリが実行できるはずです。

```graphql
query findTodos {
  todos {
    text
    done
    user {
      name
    }
  }
}
```

現時点だと、このクエリは、Todoの一覧を取得した後に、各TodoごとにTodoの登録者の情報を取得します。Todoの一覧の数が5個なら、Todo一覧処理で1回、User取得処理を5回行うことになります。User取得処理で、RDBのSELECTをしたり他のサービスのGet APIを呼ぶと、俗に言うN+1問題が起きます。

### dataloader

GraphQLのN+1問題を回避するために、dataloaderを使います。dataloaderは、複数のデータ取得リクエストを1つにまとめてくれるライブラリです。

Go製の有名なdataloaderは2つあります。

- [graph-gophers/dataloader](https://github.com/graph-gophers/dataloader/)
  - コード生成をしない方式です
  - データを取得するときに対象のデータを一意に識別するkeyを指定し、結果はResult[V any]に格納して返します。
  - keyには、intやstringなどのcomparableな型が使えます
- [vektah/dataloaden](https://github.com/vektah/dataloaden)
  - gqlgenと同じ作者です
  - Modelごとにdataloaderのコードを生成する方式です
  - データを取得するときに対象のデータを一意に識別するkeyを指定し、取得結果は取得対象のデータの型の変数に格納して返します
  - keyには、intやstringなどのcomparableな型が使えます

私は前者の方が使いやすいと思います。この記事でも前者を使います。

### dataloaderを使ったデータ取得処理の実装

#### graph/dataloaders.go

graph/dataloaders.goというファイルを作り、以下のコードを書いてください。

```go:graph/dataloaders.go
package graph

import (
	"context"
	"fmt"
	"github.com/graph-gophers/dataloader/v7"
	"github.com/kamikazezirou/gql-example/graph/model"
	"net/http"
)

type Loaders struct {
	UserById *dataloader.Loader[string, *model.User]
}

func Middleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		ctx := context.WithValue(r.Context(), loadersKey, &Loaders{
			UserById: dataloader.NewBatchedLoader(func(ctx context.Context, userIds []string) []*dataloader.Result[*model.User] {
				fmt.Println("batch get users:", userIds)

				// ユーザIDのリストからユーザ情報を取得する
				// サンプル実装なので適当な値を返していますが、プロダクト実装では以下のようにしてください。
				//   - "SELECT * FROM users WHERE id IN (id1, id2, id3, ...)"のようなSQLでDBからユーザ情報を一括取得する
				//   - 他のサービスのBatch Read APIを呼ぶ
				// それでN+1問題を回避することができます。
				results := make([]*dataloader.Result[*model.User], len(userIds))
				for i, id := range userIds {
					results[i] = &dataloader.Result[*model.User]{
						Data:  &model.User{ID: id, Name: "user " + id},
						Error: nil,
					}
				}

				return results
			}),
		})
		r = r.WithContext(ctx)
		next.ServeHTTP(w, r)
	})
}

type contextKey int

var loadersKey contextKey

func ctxLoaders(ctx context.Context) *Loaders {
	return ctx.Value(loadersKey).(*Loaders)
}

```

実装のポイントは以下です。

- dataloaderを保持するためのstruct Loadersを定義します
  - サンプルでは1つしかdataloaderがありませんが、プロダクトでは複数のdataloaderを持つことになるので、集約するstructを作っています
- net/httpのhttp.Handlerのinterceptorを作り、この中でLoadersを作成してhttp.RequestのContextに埋め込みます
  - GraphQLは通信プロトコルは普通のhttpなので、サーバもnet/httpで実現されています。リゾルバの処理の前にdataloaderを作成したいので、interceptorとして実装します。
- Loadersを作る際、NewBatchedLoaderでユーザ情報のdataloader Loaderを作ります
- NewBatchedLoaderの引数は関数になっていますが、その関数の中でDBからのReadなり、他のサービスのBach Read APIを実行するなりします。
- contextからLoadersを取り出せるようにしておきます

最後に、コードを書いたら、以下のコマンドを実行しておいてください。

```bash
go mod tidy
```

#### server.go

このファイルのhttp.Handlerを設定している箇所を以下のように変更してください。

```go:server.go
// http.Handle("/query", srv)
http.Handle("/query", graph.Middleware(srv))
```

先程作ったinterceptorを、GraphQLの処理本体の前段に設定しています。

#### graph/schema.resolvers.go

todoResolver#User()を、以下のように実装してください。

```go:graph/schema.resolvers.go
func (r *todoResolver) User(ctx context.Context, obj *model.Todo) (*model.User, error) {
	thunk := ctxLoaders(ctx).UserById.Load(ctx, obj.UserID)
	item, err := thunk()
	if err != nil {
		return nil, err
	} else {
		return item, nil
	}
}
```

Middlewareがcontextに埋め込んだDataloaderを取得して、それ経由でユーザ情報を取得します。Dataloaderの呼び出し引数には、データを一意に識別できる値を渡します。

### dataloaderの動作を見る

まず、server.goを実行して、Webブラウザでhttp://localhost:8080/を開き、Playgroundを表示してください。

次に、以下のGraphQLクエリを実行して、Todoデータを登録してください。最初に述べたように、GraphQLはRESTと異なり、1つのリクエストに複数の操作を含められます。

```graphql
mutation createTodo {
  first: createTodo(input: { text: "todo1", userId: "1" }) {
    user {
      id
    }
    text
    done
  }
  second: createTodo(input: { text: "todo2", userId: "2" }) {
    user {
      id
    }
    text
    done
  }
  third: createTodo(input: { text: "todo3", userId: "1" }) {
    user {
      id
    }
    text
    done
  }
}
```

最後に、以下のGraphQLクエリを実行して、Todoデータの一覧を取得してみてください。

```graphql
query findTodos {
  todos {
    text
    done
    user {
      name
    }
  }
}
```

dataloader導入前であればユーザ情報の取得を3回行いますが、dataloader導入後は複数のユーザ情報の取得が1回にまとめられます。

### dataloaderについての補足

#### 1. 重複したリクエストのKeyをまとめてくれる

GraphQLサーバの標準出力を見てください。以下のように出力されているはずです。

```bash
batch get users: [1 2]
```

"batch get users: [1 2 1]"とはなっていません。dataloaderはリクエストのKeyが重複しているとまとめてくれるので、こうなります。それによって無駄なデータ取得を回避できます。

#### 2. レスポンスをキャッシュしてくれる

以下の流れで処理が実行されるとします。

1. リクエストを受ける
1. datalaoderでIDが1のユーザを取得する
1. 時間のかかる処理
1. datalaoderでIDが1のユーザを取得する
1. レスポンスを返す

このとき2回目のユーザ取得の際、メモリキャッシュから値が返されます。なお、キャッシュの動作はオプションで切り替えることができます。

#### 3. 複数リクエストをまとめる挙動について

dataloaderは一定時間内のデータ取得リクエストを1つにまとめてくれます。デフォルトだと、16ms間隔でデータ取得リクエストをまとめてくれます。もちろん、この間隔の変更は可能です。また、まとめるリクエストの最大数も指定することが可能で、デフォルトは1000個です。

## スキーマ設計パターン

ここからは、GraphQLのスキーマ設計のパターンを3つ紹介します。

1. viewerクエリ：ログインユーザの取得クエリ
1. nodeクエリ：nodeを実装した型をIDから取得するクエリ
1. Connectionsパターン：Paginationのための設計パターン

ここに紹介するパターンはGitHubのGraphQL APIでも使われています。

### viewer(ログインユーザの取得)

ログインユーザの情報を取得するクエリ名は、viewerとすることが慣例です。試しに実装してみましょう。

まず、スキーマを以下のように変更してください。

```graphql:graph/schema.graphqls
type Query {
  todos: [Todo!]!
  viewer: User! # ここを追加
}
```

次に、コードを生成しなおしてください。

```bash
go run github.com/99designs/gqlgen
```

graph/schema.resolvers.goが更新され、リゾルバのメソッドにViewerが追加されているはずです。以下のように実装してください。

```go:graph/schema.resolvers.go
func (r *queryResolver) Viewer(ctx context.Context) (*model.User, error) {
	// プロダクトコードでは、ユーザを認証して、そのユーザの情報を返すようにしてください。
	return &model.User{
		ID:   "user:1",
		Name: "user1",
	}, nil
}
```

これで実装は終わりです。動作を見てみましょう。

server.goを実行して、Webブラウザでhttp://localhost:8080/を開き、Playgroundを表示してください。

実際にviewerを実行してみてください。具体的なクエリを示します。

```
{
  viewer {
    id
    name
  }
}
```

正しく実装できれば、レスポンスは次のようになります。

```
{
  "data": {
    "viewer": {
      "id": "1",
      "name": "user1"
    }
  }
}
```

### node：IDからNodeを実装した型を取得する

IDからNodeを実装した型を取得するクエリnodeを用意します。IDからデータを取得するクエリを型ごとに定義する必要がなくり、クエリの見通しが良くなります。

#### スキーマ定義とコード生成

スキーマを変更し、Todo型にNodeインターフェースを実装させ、さらにnodeクエリを追加します。

```graphql:graph/schema.graphqls
interface Node {
    id: ID!
}

type Todo implements Node {
    id: ID!
    text: String!
    done: Boolean!
    user: User!
}

type Query {
    # 他のクエリは省略
    node(id: ID!): Node
}
```

次に、Goのmodelファイルに以下のメソッドを追加します。

```go:graph/model/todo.go
func (t *Todo) IsNode() {}

func (t *Todo) GetID() string {
	return t.ID
}
```

最後に、コードを生成しなおしてください。

```bash
go run github.com/99designs/gqlgen
```

#### TodoのIDをGlobal Unique かつ 型が分かるようにする

Node interfaceを実装した型のIDは、Global Unique かつ その値から型を判定できるようにする必要があります。nodeクエリは、IDによって返すべき型が変わるからです。今回はUserにNodeをimplementsさせませんでしたが、それをimplementesさせたとします。その場合、node(id: "TodoのID")ではTodoを返し、node(id:"UserのID")だとUserを返す必要があります。IDに型情報が含まれていなければ、GraphQLサーバはTodoとUserのどちらを返したら良いか判断できません。

IDの具体例として、GitHubのGraphQL　API上でのGitHubリポジトリのIDをbase64でデコードしたものを示します。値に型情報が入っていることが分かります。

```
010:Repository12345678
```

ここまでの実装だと、TodoのIDは、"T123456"というような形式になっているはずです。一応、IDの先頭の"T"から、IDからTodo型であることが判別できますが、分かりづらいので"T"ではなく"todo:"に変更してみましょう。

```go:graph/schema.resolvers.go
func (r *mutationResolver) CreateTodo(ctx context.Context, input model.NewTodo) (*model.Todo, error) {
	todo := &model.Todo{
		Text:   input.Text,
		ID:     fmt.Sprintf("todo:%d", rand.Int()), // ここを変更
		UserID: input.UserID,
	}
	r.todos = append(r.todos, todo)
	return todo, nil
}
```

#### nodeクエリのリゾルバの実装

次に、nodeクエリのリゾルバを実装します。

```go:graph/schema.resolvers.go
func (r *queryResolver) Node(ctx context.Context, id string) (model.Node, error) {
	s := strings.Split(id, ":")
	t := s[0]

	switch t {
	case "todo":
		for _, todo := range r.todos {
			if todo.ID == id {
				return todo, nil
			}
		}
		return nil, errors.New("not found")
	default:
		return nil, fmt.Errorf("unknwon type:%s", t)
	}
}
```

#### nodeクエリを実行してみる

サーバを再起動した後、GraphQL Playgroundから、以下のクエリを実行してTodoを登録してください。結果のidはメモしておいてください。

```graphql
mutation createTodo {
  first: createTodo(input: { text: "todo1", userId: "1" }) {
    id
    user {
      id
    }
    text
    done
  }
}
```

次にnodeクエリを実行してください。Todoの情報が取得できるはずです。

```graphql
{
  node(id: "<先程登録したTodoのID>") {
    id
    ...on Todo {
      text
      user {
        id
        name
      }
    }
  }
}
```

...on Todo { } という記法ですが、nodeの戻り値はinterface Nodeなので、それをTodoに変換するためのものです。

#### IDについて補足

API ClientからnodeのIDの形式を意識させないようにしましょう。ここで実装した"todo:1"のように可読性のある形でAPI Clientに返すと、nodeのIDの形式を意識した実装をしてしまうかもしれません。なので、nodeのIDをBase64でエンコードしておくのが良いようです(機密情報ではないので完全に隠す必要はないです)。

ただ、可読性のあるIDには、GraphQL PlaygroundでAPIを試しやすいという利点もあります。不特定多数のユーザが使うAPIでない、APIユーザの教育ができる、IDの値にバイナリを含める必要がない、という状況なら、Base64でエンコードもしないのも有りだと思います。

### Connectionsパターン(Pagination)

ConnectionsパターンはPaginationのためのスキーマの設計パターンです。手を動かして理解するのが早いので手を動かしてみましょう。

このパターンの詳細を知りたい方は、[Facebook製のGraphQLクライアントjsライブラリRelayのドキュメント](https://relay.dev/graphql/connections.htm)を参照願います。

#### 一覧取得クエリの定義

まず、全てのTodoの一覧を取得するfindTodosの定義をConnectionsパターンに合わせた形に、書き換えます。

```graphql:graph/schema.graphqls
type Query {
    todos(
        after: String
        before: String
        first: Int
        last: Int
    ) : TodoConnection!
}
```

引数の意味は以下のとおりです。

- after：データ取得開始位置(cursor)を指定します
  - このcursorで指し示される項目より後の項目が取得対象になります
- before：データ取得終了位置(cursor)を指定します
  - このcursorで指し示される項目より前の項目が取得対象になります
- first：先頭からの何件取得するか
- last：末尾から何件取得するか

**補足1**
firstとlastの同時指定は、このクエリの使い方としては推奨されていません。両方同時指定されたらエラーにすると良いと思います。また、first/lastのどちらかの指定も必須にすると良いと思います。GitHubのGraphQL APIは、そういう動作になっています。

**補足2**
クエリの結果の項目の順序は、first/afterを使用する場合も、last/beforeを使用する場合も、同じにすべきです。たとえば、IDの昇順で、item1, item2, item3があるとします。このとき、一覧取得クエリの引数でfirst=3を指定した場合も、last=3を指定した場合も、結果の並びは[item1, item2, item3]とします。

#### Connection/PageInfo/Edgeの定義

続けて、スキーマに3つのtype定義を追加します。

```graphql:graph/schema.graphqls
type TodoEdge {
    cursor: String!
    node: Todo!
}

type PageInfo {
    endCursor: String
    hasNextPage: Boolean!
    hasPreviousPage: Boolean!
    startCursor: String
}

type TodoConnection {
    edges: [TodoEdge!]!
    pageInfo: PageInfo!
}
```

- Connection
  - EdgeのスライスとPageInfoを持ちます
  - 一覧取得クエリのレスポンスになります
  - Edge/PageInfo以外にtotalCountなどの付属情報を持たせるのも良いです
- PageInfo
  - startCursor/endCursor：取得した一覧の先頭と末尾の項目を指し示すcursorです
  - hasNextPage：一覧取得範囲の後に項目があるならtrue
     - 先頭から後ろの方向に一覧を取得した場合は[^1]、必須です
     - 後ろから先頭の方向に一覧を取得した場合は[^2]、オプションです
  - hasPreviousPage：一覧取得範囲の後に項目があるならtrue
     - 先頭から後ろの方向に一覧を取得した場合は、オプションです
     - 後ろから先頭の方向に一覧を取得した場合は、必須です
- Edge
  - nodeと一覧の中での位置を示すcursorを持ちます
     - 一覧がIDの昇順 or 降順だとしたら、cursorにはIDを含めておくイメージです
     - 参考：GitHubのGraphQL APIでリポジトリ一覧を取得することができますが、各Edgeのcursorは、バイナリデータをbase64でエンコードしたもので、バイナリの下4バイトはリポジトリのIDになっています
  - nodeは項目のデータ本体で、その型にはNode interfaceを実装させます

#### 実装

実装の紹介は省略します。
実装方法は想像しやすいですが、サンプル実装はかなり面倒ですので。

#### Connectionsパターンの良いところ

- cursorベースのページングなので、offsetベースのページングよりパフォーマンスが良いし、途中でデータを追加されたりしても影響を受けづらい
- このパターンに従っていると、Relay/ApolloなどのGraphQLクライアントライブラリが気を利かせてくれる
  - mutation(データ更新)のときに、クライアント側のキャッシュを更新してくれる
  - クライアント側のページングの実装が楽になる
- 一覧取得クエリの仕様がある程度統一される

## 参考資料

- [GraphQLの公式ドキュメント](https://graphql.org/learn/)
  - 文法だけでなくベストプラクティスもあります
- [ShopifyのGraphQL設計チュートリアル](https://github.com/Shopify/graphql-design-tutorial/blob/master/TUTORIAL.md)
    - 設計ガイドラインとしてどうぞ
    - [日本語翻訳](https://github.com/Shopify/graphql-design-tutorial/blob/master/lang/TUTORIAL_JAPANESE.md)もあります
- [GitHubのGraphQL Exploer](https://docs.github.com/ja/graphql/overview/explorer)
    - GraphQLを試すのに良いです
    - [スキーマをダウンロード](https://docs.github.com/ja/graphql/overview/public-schema)できるので、設計の参考にできます
- [gqlgenの公式ドキュメント](https://gqlgen.com/)
    - この記事で触れていない認証やエラーハンドリングのやり方が書かれています
- [Production Ready GraphQL](https://book.productionreadygraphql.com/)
    - GraphQLスキーマの設計、複雑すぎるクエリへの対処といったプラクティスがまとまっています。GraphQLスキーマの設計の考え方はとても参考になりました
    - 手前味噌ですが、本書のスキーマ設計の主張の概要を[別記事](https://qiita.com/zigenin/items/0331bfb05bd4bcf36366)で紹介しています

## 最後に

以上で、GoでGraphQLサーバを構築する最低限の知識を共有しました。誰かの役に立てば幸いです。

[^1]: 言い換えると一覧取得クエリのfirstを指定したときです。
[^2]: 言い換えると一覧取得クエリのlastを指定したときです。