graphql-schema

GraphQL スキーマ設計ガイド

このガイドでは、直感的で、高いパフォーマンスを発揮し、保守しやすい GraphQL スキーマを設計するためのベストプラクティスを紹介します。スキーマ設計は主にサーバー側の課題であり、API の使いやすさに直接影響します。

スキーマ設計の原則

1. クライアントのニーズを考慮して設計する

• クライアントがどのようなクエリを作成するかを考えます
• データベースのテーブルではなく、ユースケースに合わせて型を構成します
• 実装の詳細ではなく、機能を公開します

2. 明確にする

• 明確で説明的な名前を使います
• NULL 許容性を意図的に設定します
• 説明を記述します

3. 進化を見越して設計する

• 後方互換性を考慮して計画します
• 削除する前に非推奨にします
• 破壊的変更を避けます
• 新しい引数や入力フィールドには必ずデフォルト値を設定するか、NULL 許容にします。既存のクライアントはその値を送信しないため、デフォルト値のない必須フィールドを追加すると、リクエストの検証に失敗します。

クイックリファレンス

型定義の構文

"""
A user in the system.
"""
type User {
  id: ID!
  email: String!
  name: String
  posts(first: Int = 10, after: String): PostConnection!
  createdAt: DateTime!
}

NULL 許容性のルール

パターン	意味
String	NULL 許容 — null の場合があります
String!	NULL 非許容 — 常に値があります
[String]	NULL 許容リスト、項目もNULL許容
[String!]	NULL 許容リスト、項目はNULL非許容
[String]!	NULL 非許容リスト、項目はNULL許容
[String!]!	NULL 非許容リスト、項目もNULL非許容

ベストプラクティス： リストには [Type!]! を使います。null ではなく空のリストを返し、null の項目を含めないようにします。

入力型と出力型

# Output type - what clients receive
type User {
  id: ID!
  email: String!
  createdAt: DateTime!
}

# Input type - what clients send
input CreateUserInput {
  email: String!
  name: String
}

# Mutation using input type
type Mutation {
  createUser(input: CreateUserInput!): User!
}

インターフェースのパターン

interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  email: String!
}

type Post implements Node {
  id: ID!
  title: String!
}

ユニオンのパターン

union SearchResult = User | Post | Comment

type Query {
  search(query: String!): [SearchResult!]!
}

リファレンスファイル

各トピックの詳細なドキュメント：

• 型 - 型の設計パターン、インターフェース、ユニオン、カスタムスカラー
• 命名 - 型、フィールド、引数の命名規則
• ページネーション - コネクションパターンとカーソルベースのページネーション
• エラー - エラーのモデル化と結果型
• セキュリティ - スキーマ設計のセキュリティに関するベストプラクティス

主なルール

型の設計

• データの保存方法ではなく、ドメインの概念に基づいて型を定義します
• 型間で共通するフィールドにはインターフェースを使います
• 相互に排他的な型にはユニオンを使います
• 型の役割を絞ります（単一責任）
• 深いネストを避け、可能であればフラットにします

フィールドの設計

• フィールド名はクライアントの視点で付けます
• 可能な限り具体的な型を返します
• コストの高いフィールドは明示します（引数の使用を検討します）
• フィルタリング、ソート、ページネーションには引数を使います

ミューテーションの設計

• 入力引数を1つにするパターンを使います：mutation(input: InputType!)
• ミューテーションのレスポンスで、影響を受けたオブジェクトを返します
• CRUD ではなく、ビジネス操作を中心にミューテーションをモデル化します
• 成功型とエラー型のユニオンを返すことを検討します

ID 戦略

• 可能であれば、グローバルに一意な ID を使います
• 再取得できるように Node インターフェースを実装します
• 必要に応じて、複合 ID を Base64 でエンコードします

基本ルール

• 型とフィールドには必ず説明を追加します
• null にならないフィールドには必ず非NULL（!）を使います
• リストには必ず [Type!]! パターンを使います
• 無制限に増える可能性のあるリスト（Query.users や Post.comments など）は必ずページネーションを適用します。コネクションを返し、first にはデフォルトのページサイズを設定します
• スキーマでデータベースの内部情報を公開しません
• 非推奨化せずに後方互換性を損なう変更をしません
• デフォルト値なしで必須の引数や入力フィールドを追加しません
• 多数の引数よりも専用の入力型を優先します
• 固定値には任意の文字列よりも列挙型を優先します
• 識別子には String や Int ではなく ID 型を使います
• ドメイン固有の値（DateTime、Email、URL）にはカスタムスカラーを使います