Open2022/05/06にコメント追加2

[和訳まとめ] GraphQL Principles

Nayuta

元のソース

https://principledgraphql.com/

はじめに

アプリとクラウドでのサービスを接続するための問題にたいしての総合的な解決策になる。
グラフ層という新しいレイヤーを形成する。
グラフ層は会社のAppデータやサービスを１つの場所に一緒にまとめることができ、一貫性、安全性、利便性の高いインターフェースを提供するので、最小限の負担で利用することができる。
Apollo社では全体の90%をGraphQLで実装している。
あらゆる規模の企業と何千回も議論をかわしてきた中で得たベストプラクティスについて共有する。
3個のカテゴリと10個のPrinciplesで構成されている。Twelve Factor App を参考

Integirity Principles

One Graph

それぞれのチームで複数のグラフを管理するのではなく、1つのグラフで管理すること。
- GraphQLの価値を以下のように最大化することができる。
  - より多くのデータやサービスを1クエリでアクセスできる。
  - コード、クエリ、スキル、経験をチーム間で共有できる。
  - 中央集権的に利用可能データをまとめる。
  - グラフ実装が重複しないので実装コストが最小限に
  - アクセス制御ポリシーなど一元管理が可能に

Federated Implementation

グラフの各部分の実装は複数チームでやる。
- それぞれの開発リリースサイクルで行う。
- 各チームが担当グラフに責任を持つことによりグラフの統一的ビューの価値を維持しつつ全社的な開発作業を切り離すことができる。

Track the Schema in a Registry

グラフを登録、追跡するためにSingle Source of Truth（SSOT）であるべき
- スキーマレジストリで追跡することが肝要
- スキーマレジストリが、開発ツール、ワークフロー、グラフやあらゆる実際に提案された変化から利益をえ得るビジネスプロセスの動力となるようなシステムの中枢になるべき。

Agility Principles

Abstract, Demand-Oriented Schema

スキーマはサービス実装の詳細を隠しながらユーザに柔軟性を提供するような抽象レイヤとして役割を果たすべき。
- 特定のサービスや今存在する特定のユーザに対して密結合ではいけない。
- また、特定のアプリのデータ取得法とも密結合ではいけない。
- 達成するためにDemand-Oriented Schemaを利用する
  - Demand-Oriented Sdchema
    - 既存のグラフに新しい機能を追加する開発者に優れた開発体験を提供することに商店を当てたスキーマ

Use an agile approach to schema development

スキーマは実際の要件を元に段階的に構築し、時間経過とともにスムーズに進化するべき
- 憶測でフィールドを追加しない。追加機能へのコンシューマの具体的な要求に応じて追加されなければならない。
- 半年や1年で新しいバージョンをリリースするのではなく、必要であれば1日に何回もアップデートするべき。
- フィールドを取り除く場合は初めにdeprecatedにし、使用するコンシューマがいなくなってから取り除く。
- スキーマレジストリが影響を知覚できるプロセスやツールと共にグラフの俊敏な進化を可能にしている。
  - 吟味された変更のみがproductionに反映される

Iteratively Improve Performance

パフォーマンス管理は継続的、データプロセス駆動で、クエリのロードやサービス実装に柔軟に適応されるべき。
- グラフ層がサービスチームや開発者間でパフォーマンスやキャパシティについての議論を展開するのに使われるべき正しい場所である。
- この議論は、消費者がそのサービスで何をしようとしているのかをサービス開発者が継続的に、かつ事前に可視化するための継続的なプロセスであるべき。
- グラフの利用を最適化するよりも、実際にプロダクトで必要とされるクエリの形へのサポートににフォーカスを当てる。
- クエリがプロダクション化された時は、そのパフォーマンスが継続的にモニタリングされる。
- 原則に沿えば、期待どおりに動かないサービスを容易に追跡できるようになるはず。

Use Graph Metadata to Empower Developers

開発者は開発プロセス全体を通じてグラフに対する意識を豊かに持つ必要がある。
- GraphQLの価値の大部分は開発者の生産性を大幅に向上させることにある。
- その価値を最大限にするにあたり、開発者ツールは開発サイクルの全体を通して、グラフのユビキタスな（いつでも）認識を開発者に与える必要がある。
  - グラフに対するライブ情報を指先で操作できるツールである。
  - ツールは情報を常に更新し、強力な方法で目の前の状況に対してグラフへの認識を適用させる必要がある。

Operations Principles

Access and Demand Control

クライアント単位でグラフへのアクセスを認可し、クライアントが何をどのようにアクセスできるかを管理する。
- グラフの認証には2点の重要な側面がある。
  - access control（クライアントが何のフィールドをアクセスできるか）
  - demand control（クライアントがどのようにアクセスできるか）
    - ユーザがコスト（バックエンド側の負荷など）を意識せずクエリを自由に叩くことを許すのは誤りである。
- またグラフの認証にはこういった2つの側面もある。
  - オペレーションを要求するApp
  - Appを利用する人
- アクセス制御はAppを利用する人を中心とするかもしれないが、適切な要求制御は人と同じくらいAppの制御にも依存する。

Structured Logging

全てのグラフ操作の構造化ログを取得し、グラフを使用する際への理解のための重要なツールとして活用する。
- 豊富な情報をグラフ操作から取得することができる。
  - 何のユーザ、Appが操作を実行し、何のフィールドがアクセスされ、実際どのように操作が実行され、操作がどのように振る舞われるか、など
- これらの情報は非常に価値があり、今後利用可能である。
- 多くの目的で活用するべく、機械が読みやすいフォーマットで記録する。
  - ログをテキストではなく構造化した形で取得する。
- グラフ操作に関するログはトレースと呼ぶ。
  - トレース
    - ビジネス情報
      - 誰が操作を実行したか
      - 何がアクセスされ、変更されたか
      - どの開発者によってどのアプリのどの機能が構築されたか。
      - 成功したか
      - どのように実行されたか
    - 純粋な技術情報
      - どのバックエンドサービスに問い合わせるか
      - キャッシュが利用されるか
      - 各サービスがどのようにレイテンシ（遅延）に貢献しているか
- トレースは、グラフ操作における関連情報を1箇所にまとめる必要がある。

Separate the GraphQL Layer from the Service Layer

グラフ機能のレイヤードアーキテクチャをサービスごとに組み込むのではなく別の層に分割する形で採用する。
- ほとんどのAPI技術では、クライアント側は開発時を除き直接サーバ側と対話せず（開発時を除き）その代わりにロードバランシング、キャッシング、サービスロケーション、APIキー管理などの懸念事項を別の層に分離するレイヤードアーキテクチャが採用される。この層はバックエンドサービスとは別に設計、操作、拡張される。
- GraphQLの場合も同様に、グラフ機能をそれぞれのサービスに組み込むのではなく、ほとんどのグラフ機能はクライアント・サーバ間の中間層としてくくり出され、各サービスは実際のクライアント側のリクエストに対応することに集中する必要がある。GraphQL層はアクセス制御やデマンド制御 (原則8をを参照)、フェデレーション(※)、トレース収集、潜在的キャッシングなどの多様なプロセスで構成されている。
- 場合によって、この中間層はGraphQLを用いてバックエンドサービスと対話する。しかし多くの場合、既存のAPIをグラフ層の一部を形作るサーバによって実現されたグラフオブジェクトにマッピングすることで、バックエンドサービスはそのまま既存のAPI（REST, SOAP, gRPC など）によってアクセスされる。
  
  ※フェデレーション...ログインに成功していると、ログインが必要な場合でもログインが成功している状態になること

Nayuta

参考リンク集

スキーマレジストリについて