Apollo 公式キュメントを翻訳しました

https://apollographql-jp.com/

GraphQL を始める

社内の新しいプロジェクトで GraphQL を使用することにしたので、資料を読んで実装し始めました。それにあたって、有用だった資料と、実装の tips をここにまとめます。

Gatsby で GraphQL の問い合わせに慣れる

本サイトは Gatsby という React ベースの静的サイトを作成するために最適なアプリケーションを使用していますが、Gatsby はデータを取得するために GraphQL を標準で使用します。そのためのチュートリアルも丁寧に用意されており、この過程を通じで私は GraphQL のクエリを書いてデータを取得するという流れに慣れました。

この時点での私の理解は「API を Axios 等で叩く代わりに、GraphQL というシステムがあってこれに乗っ取ってクエリを投げることで、外部からデータをフェッチできる」というものでした。これが正確かどうかは現時点では私もわかりませんが、少なくとも API へリクエストを投げる仕事の領域と同等の領域のためのアプリケーションであることは理解できました。

また、Gatsby から GraphQL を始める利点の一つは、GraphQL にまつわる開発ツールが「最初から」入っているので、実装の部分でつまづくことがない、という点です。少なくともチュートリアルに沿って実行すれば、クエリを投げてデータを取得し、Component に渡してそれを表示するという流れは理解できます。

ただ当然ですが、Gatsby のチュートリアルは GraphQL のチュートリアルではないので「具体的な手順」以上の知識は手に入りません。またクライアント側からの問い合わせだけしかしませんので、GraphQL の「サーバー」をどう実装するのかということの知識も獲得できません。

GraphQL の概要については次の資料が参考になりました。

資料: アプリ開発の流れを変える「GraphQL」はRESTとどう違うのか比較してみた

アプリ開発の流れを変える「GraphQL」はRESTとどう違うのか比較してみた

2017/7 の翻訳記事で少し古いのですが、REST API と GraphQL がどう違うのか、ということを文章を中心に説明してくれています。

少なくともここで、Gatsby でなんとなく使っていた GraphQL の概要が理解できました。

GraphQL の場合、エンドポイントは一つで (それにたいして REST の場合は /user, /book のように複数のエンドポイントを作)、そのエンドポイントに対して専用のクエリを発行して、データを取得する。

なんとなく RESTful API とは違うところの雰囲気が見えてきました。

しかし、GraphQL のクライアントからの問い合わせ方法についてはなんとなく見てきましたが、問い合わせを受けるサーバー側がどういう実装になっているのか、またそのために何の資料を読めばいいのかということはわかりませんでした。

実装の実際については、次の GitHub の GraphQL API を使ったチュートリアルシリーズで概要を掴むことになります。

Getting Started with GitHub's GraphQL API

Getting Started with GitHub's GraphQL API は Github が提供している GraphQL API を使って、GraphQL を学習するチュートリアルシリーズの 1 です。

この記事では、自分の GitHub への Personal Access Token を GitHub 上で発行し、このトークンを元に GraphQL で自分のデータを取得します。

GitHub’s GraphQL Explorer

GitHub’s GraphQL Explorer を使えば、トークンを発行する必要すらありません。Sign in ボタンを押して自分の GitHub にログインすれば、即 GraphQL で自分の情報を取得することができます。まずはこれで試して見るのがいいかもしれません。

スタンドアローンの GraphQL クエリを実行するアプリ

GraphiQL.app というスタンドアローンのアプリを使うこともできます。

brew を使ってインストール
brew cask install graphiql

アプリケーションを開いたら、エンドポイントを https://api.github.com/graphql に設定します。さらに次の手順でヘッダーへ情報を追加します header name を “Authorization”、header value を “bearer [your personal access token]“ とします。

あとはクエリを実行すれば自分の GitHub からデータを取得できます。

具体的には GitHub GraphQL API にどのようなクエリを投げるのか

Github GraphQL API への具体的なクエリについては、シリーズの 2 番目の記事で扱います。

Github GraphQL API への具体的なクエリ

A GraphQL Tutorial for Beginners

シリーズ二番目の記事は、GitHub GraphQL API への具体的なクエリの投げ方について説明されています。この記事とGatsby の経験から、だいたい問い合わせの雰囲気についてはわかるはずです。

あとは、クエリをどうやってフロントから発行するのか？という部分がまだわかりません。GraphiQL のようなスタンドアローンアプリからではなく、フロントのアプリケーションの中からクエリを発行して問い合わせる方法がです。それから、GraphQL のサーバー自体をどうやって構築するのか、ということもわかりません。

この辺りで GraphQL の公式ドキュメントを少し見ることとなりました。

GraphQL 公式サイト

公式サイトのトップページ を見ると、読める、私にも読めるぞ、という気持ちになってきませんか？

type とかそのあたりはまだよくわかりませんが、問い合わせ系の部分はもうみたことがある形ですね。なるほどなるほどと。

GraphQL の問い合わせを受ける側の実装

これが一番シンプルな JS による実装 です。あーなるほど、あくまで GraphQL が提供するのは、サーバーとかではなくて、クエリを文字列で受け取ってそれに対応した値を返すという単純な関数な訳ですね。こういう実装が、JavaScript だけではなく様々な言語でできると。あくまで GraphQL は仕様を提供しているだけということがわかります。

そのうえで Apollo Server のようにウェブサーバーに GraphQL を組み込む npm が用意されていて、これを使って各種サービスを作っていくわけです。なるほどなるど。

GraphQL 完全に理解した

この辺りで GraphQL 完全に理解した、という気持ちになりますが、ではよくあるユーザーがログインして、何かアイテムを投稿して、そのアイテムを一覧表示するようなアプリケーションを GrraphQL で実装するにはどうしたらいいのか、という具体的な流れはまだよくわかりません。

これに関しては次のオライリーの本が参考になりました。

Learning GraphQL: Declarative Data Fetching for Modern Web Apps

第1章、第2章は抽象的な話なので (特に2章のグラフ理論が実装より難しい) 飛ばして、第3章くらいから読んでもらえると、今まで得た知識の再確認なのですらすら読めます。

5章の "Creating a GraphQL API" にざっくり目を通してどん感じでバックエンドを実装するのかわかってから、4章 "Designing a Schema" に戻って Schema, Type について熟読していきます。この二つの章を交互に読みながら実装していけばいいと思います。

TypeScript + React + Apollo-boost

GraphQL and Apollo Client by Example: Part 8

試しに TypeScript を使ってみているのですが、コンパイルが通らない通らない。雰囲気で TS を書いているので、よくわからない。

そこでこの記事のサンプルが役立ちました。理屈はわからないんですが、とりあえずコンパイルが通るようになった！

と思ったがやっぱり TypeScript 雰囲気では無理

やっぱり TypeScript が雰囲気でしかわからないので、そこに新技術 Apollo-client を入れるのは不可能と判断。一旦 普通の React でいってみることにした。

この辺りでバックエンドが進みそうだったので Client 側に集中

このあたりでバックエンド側の担当者から GraphQL のサーバーを建てれそうという連絡がきたので、React + Apollo Client のクライアント側の実装に集中。

最終的には GraphQL はフロント側の人間が実装した方がいいとは思っている。少なくとも Schema を読める、一緒に策定できる必要があると思う。なので GraphQL サーバーを合わせて自分も実装していきたいと思っている。

が、まずはフロント！というところで、あらためてオライリーの本にもどって React にクライアントを埋め込む作業。

翻訳記事を書きましたので、内容についてはこちらを参照ください。

がクライアント側を実装するに当たって、Schema, Types 等、結局 GraphQL 全体の知識が必要なので戻る

クライアント側を実装するに当たっても結局のとこrは Schema, Types 等、GraphQL 全体の知識が必要なので初心にかえり、上記書籍の 4,5,6 あたりをぐるぐる読んだり翻訳したりする。ここが結構長い。

Apollo の公式ドキュメントを読む

上記書籍で Apollo server の実装に入ったので、Apollo の公式ドキュメントも読む。もしかしたら、こっちを先に読んだ方が簡潔でわかりやすいかもしれない。

MongoDB を使う

GraphQL Server 側でデータを記録/読出す対象として MongoDB を参考書籍で使っていたので、人生 10度目の MongoDB チャレンジ。詳細はこちらにまとめました。