Kokia yra GraphQL schemos projektavimo gera praktika?

Question

IT Interview Practice · Accepted Answer

Gera schema yra **kliento poreikiais grįsta, kraštuose numatytai nullable ir plėtojama be versijų**. Ji modeliuoja dalykinę sritį tais terminais, kuriuos klientai realiai naudoja, o ne pagal jūsų duomenų bazės lenteles.

## Nullability

Padarykite lauką non-null (`!`) tik tada, kai galite *visada* jį grąžinti. Perdėtas `!` naudojimas yra spąstai: jei non-null laukas meta klaidą, jis paverčia null visą savo tėvinį objektą, taip mažą gedimą paversdamas dideliu tuščiu plotu. Bet kam, kas priklauso nuo tolimesnio (downstream) serviso, rinkitės nullable.

```graphql
type User {
  id: ID!             # tikrai visada yra
  email: String!      # privalomas jūsų DB -> saugu kaip non-null
  avatarUrl: String   # ateina iš išorinio serviso -> nullable, todėl jo gedimas izoliuotas
}
```

## Pavadinimai ir įvestys

- Naudokite nuoseklius, aprašomuosius pavadinimus; loginiai (boolean) skaitomi kaip teiginiai (`isPublished`).
- Kiekvienai mutacijai duokite vieną **`input`** tipą ir grąžinkite **payload** tipą — vėliau galėsite pridėti laukų nesugriaudami parašo (signature).

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

## Plėtra be versijų

GraphQL vengia `/v2` URL. Plėtojate **papildomai** (additively): laisvai pridedate laukų, o senus išimate iš rikiuotės su `@deprecated`, kol klientai migruoja.

```graphql
type User {
  fullName: String!
  name: String! @deprecated(reason: "Use fullName")   # aptarnaujame, kol klientai pereis
}
```

Lauko pašalinimas ar pervadinimas — vienintelis tikras griaunantis pakeitimas, todėl projektuokite taip, kad to prireiktų retai. Taip pat venkite atskleisti DB struktūrą (atverkite `fullName`, o ne `first_name`/`last_name`, jei klientai nori vieno lauko).

## Kodėl tai svarbu

Būtent šie pasirinkimai skiria schemą, gyvuojančią metų metus, nuo tokios, su kuria klientai kovoja. Interviuotojai tuo vertina **API projektavimo brandą** — ypač nullability/klaidų kompromisą ir papildomos plėtros (additive-evolution) mąstyseną, kurie yra unikalūs GraphQL.

Nullability

Pavadinimai ir įvestys

Plėtra be versijų

Kodėl tai svarbu

Susiję klausimai