GraphQL schema 설계의 모범 사례는 무엇인가요?

Question

IT Interview Practice · Accepted Answer

좋은 schema는 **클라이언트 주도적이고, 경계에서는 기본적으로 nullable이며, 버전 없이 진화 가능**합니다. 데이터베이스 테이블이 아니라 클라이언트가 실제로 사용하는 용어로 도메인을 모델링합니다.

## Nullability

필드를 *항상* 반환할 수 있을 때만 non-null(`!`)로 만드세요. `!`를 남용하는 것은 함정입니다: non-null 필드에 오류가 나면 그 parent 객체 전체를 null로 만들어, 작은 실패를 커다란 공백으로 바꿉니다. downstream 서비스에 의존하는 것은 무엇이든 nullable을 선호하세요.

```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
}
```

## 네이밍 & input

- 일관되고 설명적인 이름을 쓰세요; 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을 피합니다. **덧붙이는 방식으로(additively)** 진화합니다: 필드를 자유롭게 추가하고, 클라이언트가 마이그레이션하는 동안 오래된 것은 `@deprecated`로 폐기합니다.

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

필드를 제거하거나 이름을 바꾸는 것만이 유일한 진짜 breaking change이므로, 그럴 일이 거의 없도록 설계하세요. 또한 DB 형태가 새어 나가지 않게 하세요(클라이언트가 하나의 필드를 원한다면 `first_name`/`last_name`이 아니라 `fullName`을 노출하세요).

## 왜 중요한가

이런 선택들이 수년간 지속되는 schema와 클라이언트가 맞서 싸우는 schema를 가릅니다. 면접관은 이를 통해 **API 설계 성숙도** — 특히 GraphQL에 고유한 nullability/오류 trade-off와 덧붙이는 진화 사고방식 — 를 가늠합니다.

Nullability

네이밍 & input

버전 없는 진화

왜 중요한가

관련 질문