STORES で GraphQL について考えた話

hey × Da Vinci Studio
〜プロダクトの成長を支えている裏側（技術と組織）〜
https://hey.connpass.com/event/181259/

Transcript

1. STORES で GraphQL について考えた話 2020/08/27 hey × Da Vinci Studio Meetup! Takuma Chibana
2. わたしです • 知花 卓磨 • https://github.com/ta-chibana • hey（STORES.jp） • バックエンドエンジニア • こういうのを作ったりしていました →
3. 話さないこと • 本番運用した上での話 （現在実装中で、本番運用されていません ） • graphql-ruby 以外で実装する場合の話 • GraphQL についての詳細な解説 • 実装方法やコードの話
4. 話すこと • GraphQL とは？ • GraphQL を使っていて良かった点 • 課題
5. 話すこと • GraphQL とは？ • GraphQL を使っていて良かった点 • 課題
6. GraphQL とは？ • Facebook によって開発された API のためのクエリ言語 • スキーマを定義することで API の構造を型付けできる • データの取得・操作をクエリによって行う
7. GraphQL とは？ # クエリ query { items { id name categories { id name } } users { id email name } } ネストしたデータや 異なるデータを1度のリクエストで 取得することが可能 # レスポンス { "data": { "items": [ { "id": 1, "name": "Nice Book", "categories": [ { "id": 1, "name": "Book" } ] } ], "users": [ { "id": 1, "email": "taro@example.com", "name": "山田太郎" } ] } }
8. 話すこと • GraphQL とは？ • GraphQL を使っていて良かった点 • 課題
9. GraphQL を使っていて良かった点 • 実装から API のスキーマ定義やドキュメントが生成できる • GraphiQL 等のクライアントアプリが便利 • 必要なデータだけを返すことができる • エンドポイントに関する悩みが減る
10. GraphQL を使っていて良かった点 • 実装から API のスキーマ定義やドキュメントが生成できる • GraphiQL 等のクライアントアプリが便利 • 必要なデータだけを返すことができる • エンドポイントに関する悩みが減る
11. よくある問題 • 存在しないドキュメント • 誰もわからない仕様 • 「レスポンスの構造？ API を叩けばわかるぞ！」
12. GraphQL だと実装から ドキュメントを生成できる https://graphql.org/swapi-graphql/
13. スキーマも生成できる • スキーマは実装から生成することが可能 • 実装とスキーマ定義が一体になっているので OpenAPI のように YAML をメンテナンスする必要がない • デメリットもある（後述します）
14. GraphQL を使っていて良かった点 • 実装から API のスキーマ定義やドキュメントが生成できる • GraphiQL 等のクライアントアプリが便利 • 必要なデータだけを返すことができる • エンドポイントに関する悩みが減る
15. GraphiQL 等のクライアントアプリが便利 • GraphiQL … GraphQL API 用の API クライアントアプリ • ドキュメントの表示やクエリの実行が可能なツール • クエリの補完が効く • 動作確認に便利！
16. GraphQL を使っていて良かった点 • 実装から API のスキーマ定義やドキュメントが生成できる • GraphiQL 等のクライアントアプリが便利 • 必要なデータだけを返すことができる • エンドポイントに関する悩みが減る
17. 例) 同じ「アイテム」でも 一覧と詳細で必要なデータが異なる
18. 例) 同じ「アイテム」でも 一覧と詳細で必要なデータが異なる • 画像の表示数が違う
19. 例) 同じ「アイテム」でも 一覧と詳細で必要なデータが異なる • 画像の表示数が違う • 価格・説明は詳細ページのみ必要
20. 例) 同じ「アイテム」でも 一覧と詳細で必要なデータが異なる • 画像の表示数が違う • 価格・説明は詳細ページのみ必要 REST だと action を分ける必要がある
21. GraphQL だと 一覧 query { items { id name status images(first: 1) { url } } } 詳細 query { item(id: “123”) { id name status desription price images { url } } }
22. GraphQL だと 一覧 query { items { id name status images(first: 1) { url } } } 詳細 query { item(id: “123”) { id name status desription price images { url } } } 詳細では画像は 全件取得 一覧では 画像は1件のみ
23. GraphQL だと 一覧 query { items { id name status images(first: 1) { url } } } 詳細 query { item(id: “123”) { id name status desription price images { url } } } 説明と価格は 詳細でのみ必要 説明と価格は 一覧では不要
24. 必要なデータだけを返すことができる • 用途ごとに action を実装する必要がなくなる • クライアントは必要なデータだけを要求できる
25. GraphQL を使っていて良かった点 • 実装から API のスキーマ定義やドキュメントが生成できる • GraphiQL 等のクライアントアプリが便利 • 必要なデータだけを返すことができる • エンドポイントに関する悩みが減る
26. エンドポイントに関する悩みが減る REST GET /items GET /items/123 POST /items PUT /items/123 DELETE /items/123
27. エンドポイントに関する悩みが減る REST GET /items GET /items/123 POST /items PUT /items/123 DELETE /items/123 GraphQL POST /graphql 取得するリソースは クエリで指定する
28. エンドポイントに関する悩みが減る REST # ステータス変更は？ PUT /items/123 PATCH /items/123 PUT /items/123/status
29. エンドポイントに関する悩みが減る REST # ステータス変更は？ PUT /items/123 PATCH /items/123 PUT /items/123/status # アイテム詳細は？ GET /items/123
30. GET /item_info/123 GET /item_edit/123 GET /item_edit_info/123 GET /items/123/edit エンドポイントに関する悩みが減る REST # ステータス変更は？ PUT /items/123 PATCH /items/123 PUT /items/123/status # アイテム詳細は？ GET /items/123 # 必要なデータが増えてきた GET /item_detail/123
31. GET /item_info/123 GET /item_edit/123 GET /item_edit_info/123 GET /items/123/edit # アイテムの検索は？ GET /items GET /items/search GET /search_items POST /items/search エンドポイントに関する悩みが減る REST # ステータス変更は？ PUT /items/123 PATCH /items/123 PUT /items/123/status # アイテム詳細は？ GET /items/123 # 必要なデータが増えてきた GET /item_detail/123
32. GET /item_info/123 GET /item_edit/123 GET /item_edit_info/123 GET /items/123/edit # アイテムの検索は？ GET /items GET /items/search GET /search_items POST /items/search # バージョン管理は？ # する？しない？ # 本当に必要？ # バージョン上げるタイミングは？ # v1, v2 の並行運用... エンドポイントに関する悩みが減る REST # ステータス変更は？ PUT /items/123 PATCH /items/123 PUT /items/123/status # アイテム詳細は？ GET /items/123 # 必要なデータが増えてきた GET /item_detail/123
33. GET /item_info/123 GET /item_edit/123 GET /item_edit_info/123 GET /items/123/edit # アイテムの検索は？ GET /items GET /items/search GET /search_items POST /items/search # バージョン管理は？ # する？しない？ # 本当に必要？ # バージョン上げるタイミングは？ # v1, v2 の並行運用... エンドポイントに関する悩みが減る REST # ステータス変更は？ PUT /items/123 PATCH /items/123 PUT /items/123/status # アイテム詳細は？ GET /items/123 # 必要なデータが増えてきた GET /item_detail/123 現実は難しい
34. エンドポイントに関する悩みが減る • GraphQL の場合は `POST /graphql` だけなので HTTP メソッド・ URL の設計は不要に • 多数のエンドポイントを管理しなくて良くなる • フィールドへの命名は必要だが、 取得するデータはクライアントで指定できるので 比較的シンプルな命名で済む
35. 話すこと • GraphQL とは？ • GraphQL を使っていて良かった点 • 課題
36. 課題 • エラーハンドリングが難しい • 開発フローについて
37. 課題 • エラーハンドリングが難しい • 開発フローについて
38. GraphQL におけるエラーレスポンスの構造 • errors にエラー内容を含んだ オブジェクトを配列で格納 • extensions には独自のキーを含められる
39. 何が難しいか • errors はスキーマ管理対象外なので頑張りが必要 ◦ 対策しないとどのようなエラーが返るかが クライアントからは把握できない • 一般的にはステータスコードは基本的に 200 で返す ◦ 200 でエラーを返すとエラー率の変化に気づけなくなる？
40. 現状どう対応している？ • エラーコードを返し、エラーの説明をスキーマに含めている ◦ errors.extensions に code を含めて返す ◦ フィールドやオブジェクトの定義に description を 設定できるので、そこにエラーの説明を書く • 気になる点 ◦ スキーマ管理されないので型の恩恵にあずかれない ◦ 人は書かなくても良いものは忘れてしまう
41. 現状どう対応している？ • ステータスコードを REST API のように利用している ◦ 実装ミスによる意図しないエラーの増加などに気付けそう • 気になる点 ◦ 一般的な手法からは外れてしまう ◦ 返却可能なデータとそうでないデータがあるときに困る
42. 他のパターン • 回復可能なエラーを data で扱うパターン https://graphql-ruby.org/mutations/mutation_errors • 返却するデータ型と回復可能なエラーを Union Type で ラップして扱うパターン https://medium.com/@sachee/200-ok-error-handling-in-graphql-7ec869aec9bc
43. 他のパターン • 回復可能なエラーを data で扱うパターン https://graphql-ruby.org/mutations/mutation_errors • 返却するデータ型と回復可能なエラーを Union Type で ラップして扱うパターン https://medium.com/@sachee/200-ok-error-handling-in-graphql-7ec869aec9bc
44. 返却するデータ型と回復可能なエラーの型を Union Type でラップする https://medium.com/@sachee/200-ok-error-handling-in-graphql-7ec869aec9bc
45. 返却するデータ型と回復可能なエラーの型を Union Type でラップする • 失敗理由によってエラーオブジェクトの構造を柔軟に変えられる • どのようなエラーが起こりうるかが型から判断できる • クエリが複雑になる懸念がある • 返しうるエラーの種類が多い場合に問題になりそう
46. 課題 • エラーハンドリングが難しい • 開発フローについて
47. OpenAPI と比較 OpenAPI 1. スキーマを決める 2. バックエンド・フロントエンド それぞれで並行して実装 3. 結合 GraphQL(graphql-ruby) 1. バックエンド実装 2. スキーマを生成する 3. フロントエンド実装
48. OpenAPI と比較 OpenAPI • 事前にスキーマを決めるので フロントエンドと並行して 開発できる • スキーマ定義と実装が 分かれてしまう GraphQL(graphql-ruby) • スキーマは実装から生成するので 実装と定義のズレがなく、 定義に従って実装する必要もない • スキーマを得るには実装する 必要があるため、並行して 作業できない
49. 所感 • スキーマファーストで開発する場合は OpenAPI の方がやりやすそう • 生成されたスキーマをもとに話せるので 現状はこれでも大きな問題になっていない • 型を生成する部分だけ先に実装し、処理する部分（リゾルバ） の実装を後で着手するというのもありかもしれない
50. おわり • GraphQL によって API のドキュメントを頑張らなくて済むように • REST で起きていた問題を解決できる • 開発体験がとても良い • が、GraphQL であることによる課題もある