新たにGraphQLスキーマを設計する機会があり、モブプロ的にGraphQLスキーマに対していろいろ口出ししていたのだけど、そもそも前提知識をどうやって揃えたらいいのか、という話があると思う。いい機会なので、自分が読んだ本やドキュメントなどを紹介しておく。あと経験上持っている雑多なノウハウもメモしておく。
本・ドキュメント
初めてのGraphQL
そもそもGraphQLに対して入門したい、となったらまずこの本から始めるのがいいかなー。GraphQLという概念の説明から入り、サーバー・クライアント実装についてもまんべんなく触れている。2019年の本で、クライアント・サーバーの実装部分については現代だと書き方が変わっているところもあると思う。
Shopify GraphQL Design Tutorial
Shopifyがもともと社内向けに用意していたGraphQLスキーマの設計ガイド。まずはこの文書をGraphQLスキーマ設計の指針として定めておいて、必要に応じてアレンジしていくのがいいと思う。日本語版もある。
GraphQLスキーマ設計ガイド
GraphQLスキーマの設計指針やGraphQL APIの実装に関する話題から、実際にGraphQLスキーマを設計してうまくいった・いかなかった事例もまとまっている。GitHubの公開リポジトリで無料で全文が読める。
Web API: The Good Parts
GraphQL以前に、そもそもWeb APIの設計について知っておきたい場合はこれも読んでおくとよさそう。過去に読んだときの記事があったのでそっちも見てください。
GraphQLを使った共同開発の心構え 〜 フロントエンドの視点から / Hatena Engineer Seminar #18
手前味噌だけど、GraphQL APIの利用者として実際にGraphQLスキーマを育てていくための心構えとかはよくまとまっているんじゃないか。要するに、APIの利用者がやりたいことを実現できるか、を気にしたいという話になるだろう。
GraphQLスキーマの設計で考えたこと
これは同僚 (当時) の発表資料。実際のサービス・機能開発におけるGraphQLスキーマ設計のケーススタディとして読めていいと思う。限定公開・状態をどうやってGraphQLの型に落とし込むのか、の事例になっている。
apollographql/skills
AI時代なのでAgent Skillsがあるのでは？ と思って軽くググってみたところ見つかった。skills/graphql-schema/SKILL.md 単体よりは、skills/graphql-schema/references/ 以下のドキュメントを読みつつスキーマ設計の参考にする、ぐらいが人間が読むにはちょうどよさそう。
Relayに学ぶGraphQLのスキーマ設計
GraphQL Server Specificationに準拠したGraphQLスキーマにすることで、クライアント側から見たときにどのような嬉しさがあるのか、よくまとまっている。
雑多なノウハウ
union・interfaceの使い分け・使いどころ
自然言語でざっくり言い表すと、以下のようなことを意識するのがいいと思う。
- 異なる概念の集合に対して名前をつけて扱えるようにするのがunion
- 似たような概念に対して抽象化するのがinterface
あとは先述した本などでも触れられているけど、GitHubのGraphQL APIにおいてどのような概念がunion・interfaceとして定義されているのかを見てみるのも参考になるかもしれない (膨大すぎて途方に暮れるのかもしれない)。
型を分けておくとinline fragmentによって取得するフィールドを切り替えられる、ということは頭に入れておけるとよさそう。unionやinterfaceを使わずに全く同じ型を使い回すのか、union・interfaceという形で抽象化するのか、のヒントになるだろう。
GraphQL Server Specificationと id: ID! フィールド
GraphQL Server Specificationの世界観では、オブジェクトは id フィールドによって正規化されるので、異なる概念が異なる id の値を持つように注意を払う必要がある。同じオブジェクトの状態が変わったときに id の値も変わるようなことがあると混乱の元になるだろう。
他にもあると思うけど、思い出したら追記します。
