Rails で graphql-ruby を使い倒して

What would you do? 2025
https://storesinc.tech/conf/2025

Transcript

1. Rails で graphql-ruby を使い倒して (振り返り、未来へ、 RESTと比較して ) yubrot
2. Speaker
 https://yubrot.github.io/
 • HN: yubrot (ゆーぶろ)
 • Web
 • エンジニアリングマネージャ
 
 private: JITでマクロが動く自作言語処理系とか 

3. GraphQL?
 graphql-ruby?

4. STORES と GraphQL
 • STORES は色々なところで GraphQL を活用してきた
 • 我々は Ruby on Rails と共に、 graphql-ruby gem を特に多用してきた
 
 この振り返り
 
 
 Disclaimer
 • REST API という言葉を Roy Fielding 氏の提唱するそれより広義に使います
 • クライアント側触れる時間が...

5. STORES と GraphQL
 いつから： 
 2020年ごろ (サーバとレジアプリ間) 〜 
 
 どこで：
 複数のRails apps / 一部 Go, Node apps
 
 どの用途で： 
 ◯for Mobile　◯for Web Apps　◎システム間の連携 　✕APIの外部公開
 
 → 「1つのSTORES」のためのデファクトとしての採用という側面 があった
 開発の型、システム間の契約

6. (デファクトとして) GraphQL？
 言語もシステムも異なるものを繋げる → できるだけ素朴なやり方にしたい
 GraphQL は...? → 素朴に over HTTP である (※エンドポイントは1つ)
 
 よくいわれる利点： 
 • on-demand, リソースを多段に取得できる querying
 • Type-safe schemas
 
 よくいわれる疑問点： 
 • 素朴か？
 • その表現力が求められるのか？
 • 「便利」ではあるが、 too much ではないか？
 • 実装コストは？
 • 学習コストは？
 • クライアント側は？

7. GraphQL,
 graphql-rubyを
 使い倒す
 開発体験

8. 意思決定を減らす
 • API スキーマどうしよう
 ◦ OpenAPI yaml 直接書く? TypeSpec? …
 • API エンドポイントどうしよう
 ◦ /items ? /somewhere/items ?
 • データをどう表現しよう
 • このAPIでどこまで情報を返そう
 ◦ /items vs. /items/[id] ◦ ?fields=id,name,amount ?
 • ?page=1 ? ?after=id ?
 
 また、これらは API 全体で統一されているか?

9. 意思決定を減らす：GraphQL
 • API スキーマどうしよう
 ◦ OpenAPI yaml 直接書く? TypeSpec? … → GraphQL Schema
 • API エンドポイントどうしよう
 ◦ /items ? /somewhere/items ? → グラフ (閉路を持てる)
 • データをどう表現しよう → GraphQL enum, union, interface, type
 • このAPIでどこまで情報を返そう
 ◦ /items vs. /items/[id] ◦ ?fields=id,name,amount ? → on-demand querying
 • ?page=1 ? ?after=id ? → Connection Type
 

10. graphql-ruby は「意思決定の少なさ」を実装まで広げる

11. graphql-ruby は「意思決定の少なさ」を実装まで広げる

12. Batteries included: Pagination

13. Batteries included: Pagination
 def activities = object.activities
14. Batteries included: deprecation 
 field :user, Types::User, null: true, deprecation_reason: “Use reactedUser instead”
15. Batteries included: more!
 • Complexity limit
 • 命名規約
 • Global Object Identification (for caching)
 • バリデーション
 
 Rails の Convention over Configuration に近しいものがある

16. 使い倒す → よく知る
 • GraphQLをよく知る
 • graphql-rubyをよく知る
 
 学習コストが高いようで、その多くは実践的に必要なものたち 
 →
 
 • APIとして統一され、実装方法が規定されたものが
 • あらかじめ揃っている
 
 素朴にRESTで、をやりきれるか？ 独自方言を作ったり、車輪の再発明・再開発をしていないか？ 

17. NEXT：実践的な課題と向き合う
 ここまで：道具を知り型に則る話
 ここから：実践的な課題
 
 

18. NEXT：実践的な課題と向き合う
 • 利便性と引き換えに、実装コストが大きいのでは？
 • クライアントが面倒では？
 
 
 REST API でも考慮する…：
 • エラーは？
 • 認可は？
 • 運用観点は？
 • 新規に開発メンバーを迎えるには？
 
 
 

19. 我々のやり方で
 GraphQL を実践
 する

20. 最大の難所：データロード
 “performantな” データロードは明らかに困難 
 
 on-demand なクエリができるということは、 on-demand なクエリを適切に処理できる必要がある！
 
 いくつか試した中では Shopify/graphql-batch の使い勝手が良かった
 https://github.com/Shopify/graphql-batch
 
 割り切るのも選択肢ではないか ?
 クライアントは信頼できる社内の別システムであることを踏まえて…
 • 実践的に使われるクエリに応じた relation.includes をしてしまう
 • N+1 query を実際のパフォーマンス課題に応じて潰す

21. エラー (1)：アプリケーションドメインのエラーは GraphQL unionを使った表現で
 
 
 → graphql-ruby エラーの設計と実装
22. エラー (2)： “ベストエフォート” で有意な HTTP ステータスコードを返す
 GraphQL over HTTP では、 • application/json, 常に 200 と規定されていた • application/graphql-response+json という比較的新しい Content-type では、アプリケーションドメインのエラーに沿った HTTP ス テータスコードを返すことが認められている 社内ではそんなに取り組んでいない →
23. 監視運用：「できる」「サボらない」
 
 
 
 operationName や、フィールド上のエラーをトラックする
24. 監視運用：とはいえ大変…
 
 
 
 REST APIで得られるこの辺の前提が崩れる： • 標準的なHTTPツールでモニタできる • 標準的なWAFルールで保護できる • 標準的なHTTPクライアントライブラリで通信できる ※ • … ※ GraphQL も over HTTP ではあるが、 curl で一発というほど querying が簡単ではない
25. 開発の足並みを揃えていく
 • Code-first だが、コード生成結果をリポジトリにコミットする ◦ コード生成結果のdiffがないことをCIで検証する • main に入ったスキーマ変更を、 CIでセントラルなスキーマリポジトリに自動的にpushする • repository dispatch (GitHub Actions) を使い、セントラルなスキーマ リポジトリに入ったスキーマ変更を、各リポジトリにbroadcastする
26. 開発者の足並みを揃えていく
 GraphQL スキーマを通して、API設計や変更への理解度を高める • interface? union? enum? type? 決定チャート • どんな変更が破壊的か? doc
27. API設計への造詣は GraphQL 「でも」重要
 • API スキーマ をシステム間通信の契約の根幹とする • そのために、APIスキーマを共有する仕組みを整える • どう表現するか? どのような変更が破壊的なのか? 等を理解する …これらは REST API でも重要 GraphQL「だから」発生している課題ではない
28. まとめ：素朴なやり方を原則とする、デメリットを捉える
 固有の課題を捉える
 • データロードは、難しい
 • 標準的な HTTP に基づいて動作するツールとはギャップがある
 ◦ ギャップを埋める振る舞いをしたり、ひと手間をかける必要がある
 → できるだけ素朴に解決する
 
 API 設計の悩みから開放されるわけではない、引き続き向き合う課題だが GraphQLではスキーマが共通の言語としてよく機能する
29. これから
 どうしていく

30. 本当の「実践」とのギャップ
 「素朴に」としつつ、社内でもまだ実践しきれていない
 「ひとつのSTORES」を目指している中で、それはそのまま開発の足並みを 揃えられていないという課題がある 
 社内で問いかけをし、社内での見解を出していく、というのをやりきれていなかった 
 
 一方で、全てを揃えるわけでもない
 どこに、どこまで足並みを揃えたいか？ 

31. (再) GraphQL？ を問い直してみる
 素朴に over HTTP である (※エンドポイントは1つ)
 
 よくいわれる利点： 
 • on-demand, リソースを多段に取得できる querying
 • Type-safe schemas
 
 よくいわれる疑問点： 
 • 素朴に REST で良いのではないか？
 • その表現力が求められるのか？
 • 「便利」ではあるが、 too much ではないか？
 • 実装コストは？
 • 学習コストは？
 • クライアント側は？
 ←問い直す
32. REST API でやること、GraphQL でやること、どちらでもやること
 • GraphQL で最も課題になるのは運用だろう ◦ 標準的な HTTP から外れてる部分を意識する • GraphQL はクライアントからの利用の視点以外でも 開発フロー全体を下支えする • GraphQL でも REST API でもAPI設計と向き合う ◦ REST API は GraphQL と比較して規定されている部分は狭い ◦ 全体のデザインにも気を払う