エラーレスポンス設計から考える、0→1開発におけるGraphQLへの向き合い方

このデックでは、エラーレスポンス設計から考える、プロダクトの0→1開発におけるGraphQLへの向き合い方について紹介します。

旧タイトル: 「TypeScriptとGraphQLを活用した変化に強いプロダクト作り」。2024年9月9日(月) に更新しました。

ハコベル株式会社 採用情報

【著者について】

- Portfolio: bicstone.me
- X(Twitter): @bicstone_me

【この資料で発表したイベント】

- 2024年、GraphQLにどう向き合う？導入と活用の実際
- ゆめみ×LayerX×サイボウズ3社合同フロントエンドカンファレンス北海道2024後夜祭＠東京

【ページ内のURLリンク集】

3: https://findy-code.io/engineer-lab/bicstone_me
6: https://www.hacobell.com/optimization
14-1: https://github.com/dotansimha/graphql-code-generator
14-2: https://github.com/99designs/gqlgen
15: https://github.com/graphql/dataloader
21: https://spec.graphql.org/October2021/#sec-Errors
26: https://zenn.dev/p/hacobell_dev
28: https://recruit.hacobell.com/
29: https://bicstone.me/

【お詫び】

このデッキはアクセシビリティに対応しておりません。ブログ記事を後日執筆予定なので申し訳ございませんがお待ち下さい。

© 2024 Oishi Takanori

Transcript

1. ～ エラーレスポンス設計から考える ～ 0→1開発における GraphQLへの向き合い方 2024/09/10 | GraphQLにどう向き合う？導入と活用の実際 (C) 2024 Oishi Takanori ハコベル株式会社 大石 貴則 (@bicstone) 1
2. 自己紹介 ハコベル株式会社 大石貴則 (@bicstone) Certified ScrumMaster® is a certification mark of Scrum Alliance, Inc. Any unauthorized use is strictly prohibited. 高専卒の元機械エンジニア。 インターネットが世の中を変えていく のを目の当たりにしWeb業界に転身。 現在はSaaSの開発を通じて物流業界の 課題解決に正面から向き合っている。 好きなネジはイモネジ。 2
3. 宣伝 https://findy-code.io/engineer-lab/bicstone_me 3 Findy Engineer Labにインタビュー記事公開中！
4. GraphQLは、多種クライアントを想定した 不確実性が高いプロダクト開発に向いている。 しかし、柔軟性が高いが故のカオスを生み出す。 初期段階から設計を型化していくことが重要。 0→1開発におけるGraphQLへの向き合い方 4
5. 目次 プロダクトの背景 プロダクトのアーキテクチャと目論見 GraphQL活用の現状 GraphQLを採用したメリット GraphQLを採用したデメリット エラーレスポンス設計 GraphQLの向き合い方 まとめ 1 2 3 4 5 6 7 8 5
6. プロダクトの背景 引用元: https://www.hacobell.com/optimization 配車計画業務をAIで支援し、効率化と属人性解消を目 指した新規事業SaaSのMVPへ向けた開発がスタート 2022年: 物流DXの新プロジェクト立ち上げ * MVP (Minimum Viable Product、実用最小限の製品) 6
7. プロダクトの背景 アルゴリズムやUIの不確実性が存在するため、先行 導入した顧客と共同で仮説検証を実施 顧客からフィードバックを得ながら、アジャイルに プロダクト価値向上を目指す 先行導入顧客と協力しMVPを目指す → 要求の変化に機敏に対応し、 持続的に発展可能な体制が必要 7
8. プロダクトのアーキテクチャと目論見 GraphQL gRPC gRPC Frontend Backend Service A Service B ... TypeScript Go Go Python “持続的に発展可能”をキーワードに技術選定 FE、BEともに静的型付け言語を採用 フロントエンド(FE) - バックエンド(BE) 間の APIにGraphQLを採用 BE - サービス 間の通信はgRPCを採用 8
9. プロダクトのアーキテクチャと目論見 サービス間のコラボレーションにおける コミュニケーションコスト削減 多種クライアントからのアクセスを想定 スキーマから型を生成し型安全性の担保 ハコベルとしては初めてGraphQLを採用 GraphQL gRPC gRPC Frontend Backend Service A Service B ... TypeScript Go Go Python 9
10. GraphQL活用の現状 356 回 スキーマのコミット回数 2224 行 スキーマの行数 2022年3月～2024年9月の実績 11 個 Query 69 個 Mutation 10
11. GraphQLを採用したメリット 1. スキーマ駆動開発が実現 2. クライアントからクエリライクに取得可能 3. 変更の影響範囲が型で検知可能 4. Dataloaderによる効率的で安全なデータ取得 11
12. GraphQLを採用したメリット スキーマをベースにした設計議論が促進 スキーマファイル自体が立派なドキュメントになる スキーマが先行して決まることでFE, BEが並行して 作業を進めることが可能 API設計がBEに依存せずボトルネックが解決 1. スキーマ駆動開発が実現 → API設計におけるコミュニケーションコスト が削減されスムーズな開発が実現 12
13. GraphQLを採用したメリット FEは必要なフィールドを束ねて取得可能 1リクエストで済み、オーバーフェッチも阻止 UIの変化があってもFEが呼び出すクエリを変 更するのみで完結 呼び出しの変更はBEの実装変更が不要 2. クライアントからクエリライクに取得可能 → 要求の変化に対し、最小限度の実装で 応じることができ、変更コストが最小化 13
14. GraphQLを採用したメリット ライブラリを用いることで型生成が可能 TypeScript: GraphQL-Codegen [1] Go: gqlgen [2] スキーマ変更の影響範囲を型制約として静的 に検出可能 3. 変更の影響範囲が型で検知可能 → 仕様やモデルの変化を迅速かつ安全に 反映でき、アジリティが向上 14 1: https://github.com/dotansimha/graphql-code-generator 2: https://github.com/99designs/gqlgen
15. GraphQLを採用したメリット 複数のデータ取得リクエストを単一リクエスト としてバッチ処理される仕組み 永続化のロジックがシンプルになり、コードの 可読性向上 Preload忘れなどのリスクを軽減 4. Dataloader*による効率的で安全なデータ取得 → Query Resolverの実装工数が削減され API実装の高速な開発が実現 15 * https://github.com/graphql/dataloader
16. GraphQLを採用したデメリット Query Resolver, Dataloaderなどの概念/仕様 を習得する必要 仕様が最低限度で柔軟性が高いため、様々な ルールを特性に応じて検討する必要 プロダクトでは設計の見直しが複数回発生 柔軟性が高いが故の設計難易度の高さ → GraphQLのベストプラクティスの習得や スキーマ設計の型化が必須 16
17. GraphQLを採用したデメリット 設計の見直しが続いたため、後追いでDesign Patternsを作成し、設計の意思決定とその結果 を言語化して記録。 エラーレスポンス カスタムスカラ バリデーションの明示 など 柔軟性が高いが故の設計難易度の高さ 17
18. エラーレスポンスの設計 フォームのバリデーション エラーにおける事例 ユーザーフレンドリーかつ 高メンテナンス性を実現し たい プロダクト特性によって最 適な設計は異なる 検討した3パターンを紹介 Mutationにおけるエラーレスポンスの設計 18
19. パターン① 起こり得るエラーをすべてスキーマに表現する エラーレスポンス例 スキーマ例 19 ←返り値がResultに
20. パターン① 起こり得るエラーをすべてスキーマに表現する 返しうるエラーがスキーマから明確 クライアントでエラーに応じた分岐が可能 サーバーでエラー文言の管理が不要 メリット デメリット エラーコードの意味についての合意が必要 スキーマが肥大化し、実装量が増加 → クライアントでエラーハンドリングを 行いたい場合に向いている 20
21. パターン② GraphQL仕様のエラー*と併用する エラーレスポンス例 スキーマ例 ↑スキーマ上には 表現されない 21 * https://spec.graphql.org/October2021/#sec-Errors
22. パターン② GraphQL仕様のエラー*と併用する スキーマの記述量が最小限 GraphQLの仕様を活用するため実装が簡潔 サーバーに閉じているため仕様変更が容易 メリット デメリット クライアントで型を活用できずエラーハンド リングが煩雑 → 実装工数をかけたくない場合に向いている 22 * https://spec.graphql.org/October2021/#sec-Errors
23. パターン③ エラーメッセージをPayloadで返す スキーマ例 エラーレスポンス例 23 ←返り値がPayloadに
24. スキーマの記述量が少ない サーバーに閉じているため仕様変更が容易 致命的エラーとバリデーションエラーが分離 メリット デメリット 起こり得るエラーがスキーマから不明確 → 記述量を減らしつつパターン2のデメリットを許容 できない場合に向いている パターン③ エラーメッセージをPayloadで返す 24
25. エラーレスポンスの設計 プロジェクト開始時、パターン①で実装。しかし、 クライアントにエラーハンドリングが必要なく、 工数がかかるデメリットが顕著。 → プロダクト・チーム特性によって 最適な設計は異なる 25 一旦開発を止めてデザインパターンを議論し、 途中からパターン③への変更を決定
26. エラーレスポンス設計から考えるGraphQLへの向き合い方 早い段階からプロダクトの特性に応じた設計 を行い型化してくことが必要 後からの軌道修正をしやすくするため、当時 の意思決定を言語化して参照可能にする 意思決定をテックブログで社外に公開 https://zenn.dev/p/hacobell_dev 26
27. GraphQLは、多種クライアントを想定した 不確実性が高いプロダクト開発に向いている。 しかし、柔軟性が高いが故のカオスを生み出す。 初期段階から設計を型化していくことが重要。 0→1開発におけるGraphQLへの向き合い方 27
28. 最後に このプロダクトはMVP構築を達成 👏👏 引用元: https://www.hacobell.com/news/jf42_c5uj2-p プロダクト拡大のためエンジニア積極採用中です！ ハコベル 採用 [検索] 28
29. Special Thanks ハコベル配車計画チームの皆さん (いつもありがとうございます) GraphQL Error、下から見るか？横から見るか？ | by Yosuke Kurami | Medium https://quramy.medium.com/3924880be51f (Quramyさんありがとうございます) 快適にスキーマ駆動開発をするためのGraphQLエラー設計 - バイセル Tech Blog https://tech.buysell-technologies.com/entry/2023/02/21/000000 Shopify GraphQL Design Tutorial https://github.com/Shopify/graphql-design-tutorial/blob/master/lang/TUTORIAL_JAPANESE.md Error States with ErrorBoundaries | Relay https://relay.dev/docs/guided-tour/rendering/error-states/ GitHub GraphQL API documentation https://docs.github.com/ja/graphql Swan | GraphQL API Reference https://api-reference.swan.io/ Finnian Langhamさん - INFRA Original Soundtrack (神ゲーのサントラは資料作成時に流すと捗ります) 大石 貴則 (@bicstone) 登壇資料 & SNS (bicstone.me) 29