GraphQL のスキーマ設計のベストプラクティスは?

Question

IT Interview Practice · Accepted Answer

良いスキーマは **クライアント駆動で、境界ではデフォルト null 許容で、バージョンなしで進化できる** ものです。データベースのテーブルではなく、クライアントが実際に使う言葉でドメインをモデル化します。

## null 許容性

フィールドを非 null (`!`) にするのは、*常に* 返せる場合だけにしてください。`!` の使いすぎは罠です: 非 null フィールドがエラーになると親オブジェクト全体を null にし、小さな失敗が大きな空白に変わります。ダウンストリームのサービスに依存するものは null 許容にするのが望ましいです。

```graphql
type User {
  id: ID!             # truly always present
  email: String!      # required in your DB -> safe as non-null
  avatarUrl: String   # comes from an external service -> nullable, so its failure is isolated
}
```

## 命名と入力

- 一貫した説明的な名前を使いましょう。boolean は述語として読めるように (`isPublished`)。
- すべての mutation に単一の **`input`** 型を与え、**payload** 型を返しましょう — 後からシグネチャを壊さずにフィールドを追加できます。

```graphql
input CreatePostInput { title: String!, body: String! }
type CreatePostPayload { post: Post!, errors: [UserError!]! }  # room to grow
type Mutation { createPost(input: CreatePostInput!): CreatePostPayload! }
```

## バージョニングなしの進化

GraphQL は `/v2` の URL を避けます。**追加的に** 進化させます: フィールドは自由に追加し、古いものは `@deprecated` を付けてクライアントが移行する間、提供し続けます。

```graphql
type User {
  fullName: String!
  name: String! @deprecated(reason: "Use fullName")   # keep serving until clients move off
}
```

フィールドの削除やリネームだけが唯一の真の破壊的変更なので、それがめったに必要にならないよう設計します。また DB の形を漏らさないようにしましょう (クライアントが 1 つのフィールドを望むなら `first_name`/`last_name` ではなく `fullName` を公開する)。

## なぜ重要なのか

これらの選択が、何年も持続するスキーマと、クライアントが戦うことになるスキーマを分けます。面接官はこれで **API 設計の成熟度** を測ります — 特に null 許容性/エラーのトレードオフと、GraphQL 特有の追加的進化の考え方です。

null 許容性

命名と入力

バージョニングなしの進化

なぜ重要なのか

関連する質問