Quais são as boas práticas de design de schema GraphQL?

Question

IT Interview Practice · Accepted Answer

Um bom schema é **orientado ao cliente, nullable por padrão nas bordas e evoluível sem versões**. Ele modela o domínio nos termos que os clientes realmente usam, não nas suas tabelas de banco de dados.

## Nullability

Torne um campo non-null (`!`) apenas quando você *sempre* consegue retorná-lo. Abusar de `!` é uma armadilha: se um campo non-null dá erro, ele anula todo o seu objeto pai, transformando uma pequena falha em um grande vazio. Prefira nullable para qualquer coisa que dependa de um serviço downstream.

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

## Nomenclatura & inputs

- Use nomes consistentes e descritivos; booleanos se leem como predicados (`isPublished`).
- Dê a cada mutation um único tipo **`input`** e retorne um tipo **payload** — você pode adicionar campos depois sem quebrar a assinatura.

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

## Evolução sem versionamento

O GraphQL evita URLs `/v2`. Você evolui de forma **aditiva**: adicione campos livremente e aposente os antigos com `@deprecated` enquanto os clientes migram.

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

Remover ou renomear um campo é a única mudança realmente disruptiva, então projete de modo que você raramente precise. Evite também vazar o formato do banco (exponha `fullName`, não `first_name`/`last_name`, se os clientes querem um campo único).

## Por que isso importa

Essas escolhas são o que separa um schema que dura anos de um contra o qual os clientes lutam. Os entrevistadores usam isso para avaliar a **maturidade em design de API** — especialmente o trade-off de nullability/erro e a mentalidade de evolução aditiva, que são exclusivos do GraphQL.

Nullability

Nomenclatura & inputs

Evolução sem versionamento

Por que isso importa

Perguntas relacionadas