GraphQL schema tasarımı için en iyi uygulamalar nelerdir?

Question

IT Interview Practice · Accepted Answer

İyi bir schema **istemci odaklıdır, kenarlarda varsayılan olarak nullable'dır ve versiyonlar olmadan evrilebilir**. Alan adını, veritabanı tablolarınızla değil, istemcilerin gerçekten kullandığı terimlerle modeller.

## Nullability

Bir alanı yalnızca *her zaman* döndürebiliyorsanız non-null (`!`) yapın. `!`'i aşırı kullanmak bir tuzaktır: non-null bir alan hata verirse, tüm parent nesnesini null yapar ve küçük bir hatayı büyük bir boşluğa dönüştürür. Bir alt akış (downstream) servisine bağlı her şey için nullable tercih edin.

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

## Adlandırma ve input'lar

- Tutarlı, açıklayıcı adlar kullanın; boolean'lar bir yüklem gibi okunur (`isPublished`).
- Her mutation'a tek bir **`input`** tipi verin ve bir **payload** tipi döndürün — imzayı bozmadan daha sonra alan ekleyebilirsiniz.

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

## Versiyonlama olmadan evrim

GraphQL `/v2` URL'lerinden kaçınır. **Ekleyerek (additively)** evrilirsiniz: serbestçe alan ekleyin ve istemciler geçiş yaparken eskilerini `@deprecated` ile emekliye ayırın.

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

Bir alanı kaldırmak veya yeniden adlandırmak tek gerçek kırıcı değişikliktir, bu yüzden buna nadiren ihtiyaç duyacak şekilde tasarlayın. Ayrıca DB şeklini sızdırmaktan kaçının (istemciler tek bir alan istiyorsa `first_name`/`last_name` değil, `fullName` sunun).

## Neden önemli

Bu seçimler, yıllarca dayanan bir schema ile istemcilerin ona karşı savaştığı bir schema arasındaki farktır. Mülakatçılar bunu **API tasarım olgunluğunu** ölçmek için kullanır — özellikle GraphQL'e özgü olan nullability/hata ödünleşimini ve ekleyerek-evrim zihniyetini.

Nullability

Adlandırma ve input'lar

Versiyonlama olmadan evrim

Neden önemli

İlgili sorular