OREIlly本「初めてのGraphQL」をつまづかないために。

全般

みなさん、こんにちは!
次の祝日は7月18日という事実と向き合えず、だいぶ落ち込んでる佐々木です!

さて、みなさんは今年のGWで何かしら新しい学びはありましたか?
僕はまとまった休みということもあり、「GraphQL」に入門してみました!(今更!)
今回は、お世話になった本も含め、読みすすめていく過程で、つまづいたりしたところを紹介できればなと思います!

GraphQL

GraphQL は、API の速度、柔軟性、開発者にとっての使いやすさを向上させるために設計された、API向けのクエリ言語・ランタイムです。
特徴としては、以下のようなものが挙げられます。

  • クライアントがリクエストした「必要なデータのみ」を取得することができる。
  • 1回のリクエストで必要なデータを取得することができる。(エンドポイントが1つで済む)
  • データ型を定義することより、サーバーサイド側とのデータ型の不整合を防ぐことができる。

上記の特徴とは別に、GraphQLを実装する際にスキーマを定義する必要があるわけですが、このスキーマがそのままドキュメントになるという点はすごく良いですよね。
どこから手を付けようか色々と調べた結果、OREIlly本「初めてのGraphQL」の購入に至りました。
主観ではありますが、ページ量も程々に体系的に学べるようにまとまっており、ハンズオン形式ですすめるのが好みの僕には向いていた書籍でした。

初めてのGraphQL
今日では多くのWebサービスがRESTアーキテクチャスタイルで実装されています。RESTは2000年にフィールディングの論文で提唱された後に爆発的に普及し洗練されてきました。一方で、本書で紹介するGraphQLは2015年にFacebookによって公開されたRESTとは異なるアプローチのアーキテクチャです。GraphQ...

ですが、こちらの書籍は出版されてから少し日が経っており(初版第二刷が2020/4/15と記載)、文中のリンク先が現在は使用できないものや、記載されているコードがそのまま使用出来ないなど、ちらほら調べる必要がありました。
リンク先くらいであれば特段苦労しないのですが、言い回しの部分などで少々わかりにくい箇所は手が止まってしまうことがあり、「そういうことか!」と理解するのに時間がかかってしまいました。(翻訳されている文章なので、言い回しが独特になるのは実際仕方ないと思いますが)

以下では、書籍中で僕がつまづきそうになった(というか、つまづいた)箇所をいくつかご紹介します。同じような箇所で時間を浪費されている方がいれば参考にしていただければなと思います。

本の構成

本は全七章で構成されています。

1章から2章はGraphQlの歴史や背景、グラフ理論についてなどの紹介がメイン。

3章から4章はGraphQLの書き方、お作法、クライアントツールの紹介とスキーマ定義について解説。

5・6章ではGraphQLサーバー、GraphQLクライアントの実装。

7章では、GraphQLを本番環境で動かす想定として、セキュリティの部分やリアルタイムでの更新のためのWebSocketを実装するなど。

「体系的に学べる」系の本は概ね前半までは用語とか概念、お作法といった学ぶ上での事前知識を植え付けさせて、後半にかけて実際にやってみる。
といった流れで進んでいくので、「ある程度知ってるからとりあえず動かしたい!」って方は前半飛ばすのも全然ありかなと思います。(その際は、この本は五章からが対象になります。)

カスタムスカラー型

書籍では、「5.2.5 カスタムスカラー型」の章になります。

GraphQLには、BooleanIntFloatStringIDといった標準のスカラーが存在します。
それとは別に独自スカラーを定義する事もできます。(本書中ではDateTime型として作成します)
カスタムスカラーは5章で登場するのですが、ここで3つのメソッドが紹介されます。

  • serialize
    →定義してある関数に従い、レスポンスに含める処理を行う。
  • parseValue
    →クライアント側から送る値を引数に追加する前に任意の処理を行う。
  • parseLiteral
    →クライアント側から送る値がリテラル(ハードコーディング)の際に実行する処理を行う。

それぞれクライアント側から引数を伴うリクエストを行った際に使用されるメソッドですが、書籍中では、いきなり解説に入るのでドキュメントを先に見ておくとスムーズに理解できそうです。

Custom scalars

MongoDBのインストール

書籍では、「5.4.1 MongoDBのインストール」の章になります。

こちらについてはつまづいたわけではないんですが、「わざわざインストールしたくないなぁ。。」
ということ個人的な意向もあり、Dockerで解決させました。
ただし、書籍内での解説内容などにも影響があるので、推奨はしません。ある程度自分で解消できるのであればこの選択もあるよ。という程度に認識してください。

新規でdocker-composeを作成します。

docker-compose.yml

version: '3'

services:
  mongo:
    image: mongo:5.0.3
    ports:
      - "27017:27017"
    volumes:
      - ./mongo:/docker-entrypoint-initdb.d
    environment:
      MONGO_INITDB_ROOT_USERNAME: user
      MONGO_INITDB_ROOT_PASSWORD: password
      MONGO_INITDB_DATABASE: example
      TZ: Asia/Tokyo

書籍内では.envでDB_HOSTの環境変数を以下のように表現してます。

DB_HOST=mongodb://localhost:27017/<Your-Database-Name>

上記の内容を置き換えます。

DB_HOST=mongodb://user:password@127.0.0.1:27017/example?authSource=admin

「authSource=admin」を指定している理由として、authSource が指定されていない場合、authSource のデフォルトは、接続文字列で指定された defaultauthdb になります。
defaultauthdb が指定されていない場合、authSource のデフォルトは admin になるためです。(以下に公式リンク貼っておきます)

Connection String URI Format — MongoDB Manual

githubAuthミューテーション

書籍では、「5.5.3 githubAuthミューテーション」の章になります。

こちらでは、GithubAPIでユーザー認証を経て、情報を取得する流れで進みます。

認可コード取得後にクライアントからgithubAuth ミューテーションを送信する手順ですが、このままではアクセストークンが返ってきません。

これはGithubのAPI認証が既存のコードだと非推奨の形になっているためです。
以下のリンクで確認できます。

Deprecating API authentication through query parameters
Get started with one of our guides, or jump straight into the API documentation.

中身を見てもらえればわかると思いますが、トークンをクエリパラメータに含めず、ヘッダーで渡してねってことなので、記載のコードを修正します。(書籍では、lib.jsが対象のファイルです)

lib.js

const requestGithubUserAccount = token => 
    fetch(`https://api.github.com/user?access_token=${token}`)
        .then(res => res.json())

こちらを以下のように書き換えます。

const requestGithubAccount = token =>
    fetch(`https://api.github.com/user`,
        {
            method: 'POST',
            headers: {
                'Authorization': `token ${token}`,
            }
        }
    )

実は自分の環境では認証は通るようになったものの、アクセストークンがレスポンスに返って来なかったため、暫定対処として適当な箇所にconsole.logを置いてそこから取り出しました。

読み終わった感想

古い情報が多かったとはいえ、なんとか読み進めることが出来てちょっとした達成感はありました。もしかしたらそのうち新しいGraphQL本が出るかもしれませんね。
ハンズオン形式で学ぶのであれば、UdemyとかCouseraみたいなプラットホームもありますし、本よりもつまづきにくいと思いますが、説明や解説については活字のほうが頭に入ってくる印象です。(これは個人差だと思いますが(笑))
あと、この書籍ではApolloClient、ApolloServerを使って手順をすすめるので、公式のドキュメントを見ながら読み進める方が良いと思います。

みなさんもどこかでGraphQLを使う機会があれば、こちらの書籍を手にとってみては如何でしょうか?

ではまた!

コメント