GraphQL APIマージリクエストチェックリスト

GitLab GraphQL APIはかなり複雑なので、GraphQLの変更を含むマージリクエストはGraphQLに詳しい人がレビューすることが重要です。MR の@gitlab-org/graphql-experts グループか、Slack の#f_graphql チャンネル (GitLab チームメンバーのみ利用可能) から ping を送ることができます。

GraphQLクエリのレビューが必要です：

  • 変更点
  • 作成者
  • パフォーマンス

レビュー基準

これは網羅的なリストではありません。

サンプルクエリを含む説明

説明文にサンプルクエリが含まれていることを確認してください。ローカルのGDKインスタンスでGraphiQLのクエリを実行してみてください。

破壊的な変更はありません（完全な非推奨サイクルの後でない限り）。

MRに変更がないか確認してください。

もし、その機能がExperimentとしてマークされていれば、非推奨期間なしで、すぐに変更を加えることができます。

詳しくは、非推奨と削除のプロセスをご覧ください。

マルチバージョンの互換性

マルチバージョンの互換性が保証されていることを確認します。これは一般的に、同じGraphQL機能のフロントエンドとバックエンドのコードを同じリリースで出荷できないことを意味します。

詳細については、複数バージョンの互換性を参照してください。

テクニカルライティングレビュー

生成されたAPIドキュメントの変更には、テクニカルライターのレビューが必要です。

チェンジログ

エクスペリメントとしてマークされていない公開された変更には、変更ログエントリーが必要です。

フレームワークを使う

GraphQLは多くの可動部分を持つフレームワークです。フレームワークに従うことが重要です。

  • フレームワークのビットを手動で起動しないでください。たとえば、実行中にリゾルバをインスタンス化せず、フレームワークに任せます。
  • MyResolver.single のようにリゾルバをサブクラス化することができます (リゾルバの派生参照)。
  • より複雑な引数ロジックにはready? メソッドを使用してください（resolver#ready の正しい使用法を参照）。
  • より複雑な引数の検証にはprepare メソッドを使用します（引数の検証を参照）。

詳細はリゾルバガイドを参照ください。

作成者

適切なオーソライズが行われ、authorize :some_ability がスペックでテストされていることを確認します。

詳細については、作成者ガイドを参照してください。

パフォーマンス

保証します：

適切なタイプを使いましょう

使用例：

  • TimeType RubyTime およびDateTime オブジェクトの場合。
  • id フィールドのグローバル ID

詳細はタイプをご覧ください。

適切な複雑さ

クエリの複雑さとは、クエリがどの程度高価になりそうかを定量化する方法です。クエリの複雑さの限界は、スキーマの定数として定義されます。リゾルバや型の呼び出しにコストがかかる場合は、クエリの複雑さにそれを反映させる必要があります。

詳細はmax complexity、field complexity、query limitsを参照してください。

テスト

  • リゾルバ（ユニット）仕様は廃止され、リクエスト（インテグレーション）仕様が採用されます。
  • 私たちのフレームワークの多くの側面は、resolve メソッドの外側にあり、リクエスト仕様はそれらが適切に動作することを保証する唯一の方法です。
  • すべてのGraphQLの変更MRは、理想的にはAPI仕様に変更を加えるべきです。

詳細はテストガイドを参照してください。