Jakie są dobre praktyki projektowania schematu GraphQL?

Question

IT Interview Practice · Accepted Answer

Dobry schemat jest **sterowany klientem, domyślnie nullowalny na brzegach i możliwy do rozwoju bez wersjonowania**. Modeluje domenę w kategoriach, których klienci faktycznie używają, a nie tabel bazy danych.

## Nullowalność

Oznaczaj pole jako non-null (`!`) tylko wtedy, gdy *zawsze* możesz je zwrócić. Nadużywanie `!` to pułapka: jeśli pole non-null się nie powiedzie, zeruje cały obiekt nadrzędny, zamieniając małą awarię w dużą pustkę. Dla wszystkiego, co zależy od usługi downstream, preferuj nullowalność.

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

## Nazewnictwo i inputy

- Używaj spójnych, opisowych nazw; wartości logiczne czyta się jak predykaty (`isPublished`).
- Nadaj każdej mutacji pojedynczy typ **`input`** i zwracaj typ **payload** — dzięki temu możesz później dodawać pola bez łamania sygnatury.

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

## Rozwój bez wersjonowania

GraphQL unika adresów URL typu `/v2`. Rozwijasz go **addytywnie**: dodawaj pola swobodnie, a stare wycofuj przez `@deprecated`, podczas gdy klienci migrują.

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

Usunięcie lub zmiana nazwy pola to jedyna prawdziwa zmiana łamiąca, więc projektuj tak, byś rzadko jej potrzebował. Unikaj też ujawniania kształtu bazy danych (udostępnij `fullName`, a nie `first_name`/`last_name`, jeśli klienci chcą jednego pola).

## Dlaczego to ważne

Te wybory odróżniają schemat, który trwa latami, od takiego, z którym klienci walczą. Rekruterzy używają tego, aby ocenić **dojrzałość w projektowaniu API** — zwłaszcza kompromis nullowalność/błędy oraz nastawienie na rozwój addytywny, które są unikalne dla GraphQL.

Nullowalność

Nazewnictwo i inputy

Rozwój bez wersjonowania

Dlaczego to ważne

Powiązane pytania