GraphQL スキーマ設計基本方針の案 その2

どこかでつかったGraphQLスキーマ設計資料

Transcript

1. GraphQL "スキーマ設計基本方針"の案 その2
2. 命名規則
3. 型名はPascalCase, フィールド名は camelCase
4. イニシャリズム、アクロニムも先頭の文字だけ 大文字にする SSO や HTTP のような名前と相性が悪いコード生成ツールが ある。
5. enumはUPPER_SNAKE_CASEにする 統一されていることが重要
6. scalarを活用する
7. scalarを定義することで書式やルールをもつ値を表現すること ができる。
8. B/Eが得られるメリット (Go - gqlgenの場合)
9. 変換処理を書くことで、リゾルバーでは変換されたデータを受 け取ることができる。
10. F/Eが得られるメリット (graphql-codegenの場合)
11. スキーマからmockデータを生成するライブラリで、scalarに 対するダミーデータのデータ形式を指定できたりする。
12. 後方互換性を保つ
13. GraphQLの基本思想はバージョンレス。 少なくとも一度の更新でフィールドの非推奨化と削除を同時に 行ってはならない。
14. フィールドを非推奨化するには @deprecated ディレクティ ブを使用する。
15. MutationのInputとPayload
16. Mutationの引数はそれぞれ専用のInput1つに する？
17. 古いRelayの仕様の名残らしく、あまりメリットはない。 長いものには巻かれろ（？）
18. Mutationはそれぞれ専用のPayloadを返す
19. 大前提として、Mutationは更新されたリソースを返 すべき クライアントライブラリがキャッシュを自動的に更新すること ができる。
20. リソースをそのまま返してしまうと、追加で返したいフィール ドが増えた場合に破壊的変更となってしまう。 => 専用のPayload型を使おう
21. Mutationを多機能にしない
22. 実装やメンテナンスのコストが跳ね上がるため、ひとつの Mutationに持たせる機能は1つだけになるようにする。
23. "データ型+操作(作成/更新/削除)"の単位でmutationを切ると 大変なことになる。
25. 以下のようなクエリを書くことで、一つのクエリを使って選択 的なデータ更新を行うことはできる。 @include とは逆の @skip ディレクティブもある。
26. セキュリティ関連
27. GraphQLではクライアントが任意のクエリを投げることができ る。 ↓ 要求された全てのフィールドを解決しようとすると サーバーに想定外の負荷がかかってしまう場合がある
28. クエリの複雑性に制限をかける
29. クエリの複雑性=8
30. クエリをパースした後に複雑性(complexity)を計算する。 複雑性が一定以上であれば、フィールドの解決を一切行わずに エラーを返すことができる。
32. gqlgenでは以下のようにフィールド単位の複雑性の計算方法を 設定することができる。 mailAccounts フィールドは、解決するまで項目数がわか らない 仕様で上限が決まっている場合には、その上限いっぱいにデ ータを返すことを想定して計算する （あまりやりたくないパターン）
33. クエリの複雑性=24
34. ページネーションされるフィールドでは、ペー ジあたりの最大項目数を引数として受ける
35. アドレス帳の1ページ目にある連絡先を取得するクエリ。
36. 引数としてページあたりの最大項目数を受けているため、クエ リから複雑性を導くことができる。
37. クエリの複雑性=202
38. ページあたりの項目数を引数にすることで、複雑性の計算が 簡単になる "ページあたりの項目数"の決定は本来F/Eの責務 スキーマでデフォルト値を記述することもできる B/Eでは有効な値の範囲を決めておく必要がある 範囲を示すディレクティブがあっても良い @range(min: 1, max: 200)
39. このようなクエリでも、複雑性を計算して受け入れるかどうか を合理的に判定することができる。
40. 複雑性の閾値は計測しながら決めていくしかないようです。
41. Introspection/GraphiQL ぐ ら ふ ぃ か る の無効化
42. パブリックAPIでない限り、本番環境ではGraphiQLのようなプ レイグラウンドを公開するべきでない。 同様に、スキーマ情報を取得できるIntrospectionも無効化し ておく。 OWASP Cheat Sheet Series - GraphQL Cheat Sheet
43. エラーレスポンスに実装の情報が入り 込まないようにする
44. GraphQLに限りませんが、エラーレスポンスにスタックトレー スやライブラリのエラーメッセージなどを含まないようにしま しょう。