| Status | Authors | Coach | DRIs | Owning Stage | Created |
|---|---|---|---|---|---|
| accepted |
@grzesiek
|
@ayufan
@grzesiek
|
@dsatcher
@deuley
| devops manage | 2021-01-07 |
GraphQL API
GraphQLはAPI用のデータクエリおよび操作言語であり、既存のデータでクエリを実行するためのランタイムです。
GitLabでは、GraphQLを採用することで、より多くのコミュニティが信頼できる方法でGitLabと簡単にやり取りできるようにしたいと考えていますが、GraphQLを使用してバックエンドとフロントエンドのコンポーネント間の通信をモデル化することで、私たち自身の製品も進化させたいと考えています。
私たちは最近、GraphQLマイグレーションに関連する四半期ごとのOKRを定義することで、採用のペースを上げました。その結果、私たちはGraphQL開発に多くの時間を費やすようになり、新しいAPIを拡張するために使用するツールを改善する必要性を表面化するのに役立ちました。
このドキュメントでは、私たちの開発者の努力とGraphQL API の大規模な使用をサポートする安定した基盤を構築するために必要な作業について説明します。
要約
GitLabのGraphQLイニシアチブは3年ほど前に始まりました。GraphQLエコシステムに関する作業のほとんどは、GraphQLの専門家であるボランティアによって行われてきました。
私たちの進捗を振り返ることで、GraphQL 開発の取り組みを効率化し、GraphQL API をスケールで観測可能かつ操作可能にするために必要な本質的なメカニズムのギャップに関連する可能性のあるパフォーマンス低下や停止の可能性のリスクを低減するためのいくつかの機会が浮上しました。
GraphQLエンジン自体への小さな改善の中で、私たちはチームメンバーが私たちのGraphQL API内部で起こっていることを理解できるようにする包括的な監視ダッシュボードを構築したいと考えています。SLOを定義し、違反したSLIをトリアージし、GrafanaとElasticを使って関連する詳細にズームインできるようにしたいと考えています。過去のデータを見たり、将来の利用状況を予測したりしたいのです。
REST API を進化させ、規模を拡大した経験から学び、この知識を GraphQL 開発の取り組みに応用するチャンスです。クエリからフィーチャーへの相関メカニズムを構築し、スケーラブルな状態同期サポートを追加し、ダイレクトアップロードのサポートのように、並行して実行されている他のアーキテクチャイニシアティブとGraphQLを整合させることで、それを行うことができます。
GraphQLはデフォルトでセキュアであるべきです。私たちは、私たちに関連するOWASP GraphQL勧告を実施するのに役立つメカニズムを構築することで、一般的なセキュリティミスを避けることができます。
また、より広いコミュニティのニーズを理解することで、より良い非推奨ポリシーを計画し、彼らのニーズに合ったGraphQLとREST API間のパリティを設計することができます。
課題
GraphQLで起こっていることを理解すること
本番環境でGraphQLがどのように動作するかを確認できることは、そのサービスのパフォーマンスと信頼性を向上させるための前提条件です。
GraphQL がどのように動作し、最適化すべきボトルネックは何かという問いに答えることを可能にするツールはまだありません。このことは、GraphQL の採用ペースと私たちが期待するオペレーション規模と相まって、解決が困難な本番インシデントの発生率が増加するリスクをもたらします。
私たちは、GraphQL エンドポイントがどのように実行されているかのインサイトを提供することに重点を置きつつ、チームメンバーに詳細を拡大する機能を与える包括的な Grafana ダッシュボードを構築したいと考えています。ロギングを改善し、Elasticを使用した機能とGraphQLクエリの関連付けを改善し、パフォーマンスの問題を早期に検出できるようにインデックス化したいと考えています。
- GraphQL用の包括的なGrafanaダッシュボードの構築
- GraphQLクエリからフィーチャーへの相関メカニズムの構築
- ElasticにおけるGraphQLクエリのロギングの改善
- フロントエンドのエラー処理を再設計し、警告を表面化
揮発性のGraphQLデータ構造の管理
私たちのGraphQL APIは時間とともに進化していきます。GraphQLはそのような進化を容易にするように設計されています。GraphQLはComposerであるため、GraphQL APIは拡張しやすくなっています。一方で、これはGraphQL APIのバージョン管理が不要とされる理由でもあります。APIをバージョン管理する代わりに、いくつかのフィールドを非推奨としてマークしたいのですが、非推奨のフィールドや型の使用状況を理解する方法と、それを理解しやすい方法で視覚化する方法が必要です。非推奨フィールドの使用を検出し、削除する予定であることをユーザーに通知したいかもしれません。
- ユーザーにより良いサービスを提供するために、データに基づいた非推奨ポリシーを定義します。
- 非推奨のGraphQLフィールドの使用頻度を示すダッシュボードの構築
- Service Pingで非推奨のフィールドを送信するために必要なメカニズムを構築します。
他のコードベースとの整合性の確保
私たちが取り組んでいるのは GraphQL だけではありませんが、アプリケーション全体にわたっています。私たちの製品のほぼすべての部分で収集・処理されたデータを公開するために使用されています。そのため、私たちのモノリシックなコードベースと緊密に結合しています。
私たちがGraphQLをどのように使うかは、GitLabのパフォーマンスと信頼性を向上させるために私たちが設計した他のメカニズムとの一貫性を確保する必要があります。
私たちは REST API を進化させた豊富な経験があります。この知識をGraphQLに適用し、デフォルトでパフォーマンスとセキュリティを向上させたいと考えています。
- GraphQLの直接アップロードの設計
- GraphQLクエリの深さと複雑さのヒストグラムの構築
- 限界に達したGraphQLクエリの量を視覚化
- 既存機能のGraphQL ETagsサポートを追加
REST APIとのGraphQL相互運用性の設計
私たちは REST API を廃止するつもりはありません。GitLabとやりとりするシンプルな方法であり、GraphQLが従来のREST APIを完全に置き換えるものにはならないかもしれません。2つのAPIは共存していく必要があるでしょう。両者のコードベースをメンテナーにするために、両者間の重複を取り除く必要があるでしょう。しかし、この共存はバックエンドで解決しなければならない技術的な課題だけではありません。ユーザーは2つのAPIを互換的に、あるいは同時に使いたいと思うかもしれません。リソース識別子の共通スキームを公開することで相互運用性を持たせることは、相互運用性の前提条件です。
- GraphQL と REST API を相互運用可能にします。
- 両APIに共通のリソース識別子を設計
スケーラブルな状態同期メカニズムの設計
GitLabにおけるGraphQLの採用に関する最も重要な目標の一つは、GitLabのバックエンドとフロントエンドのコンポーネント間のインタラクションをモデル化するためにGraphQLを使用することです。これは現在進行中のプロセスであり、より良い状態同期メカニズムを構築したり、既存のものにフックしたりする必要性がすでに表面化しています。
- スケーラブルな状態同期メカニズムの設計
- pub/subとwebsocketによる状態同期の評価
- GraphQL機能相関と機能ETagsの汎用サポートの構築
- 共有グローバル・ステートの管理を担当するフロントエンド・コードの再設計