Skip to content

GraphQL Folha de referência

Linguagem de consulta e runtime para APIs.

01

Primeiros passos

Query básica

O GraphQL permite que os clientes especifiquem exatamente quais dados precisam. Uma query busca dados, e a resposta espelha a forma da query. Isso evita o over-fetching e under-fetching comuns em APIs REST.

graphql
# Query - read data
query {
  user(id: 1) {
    id
    name
    email
    posts {
      title
      content
    }
  }
}

# Response
{
  "data": {
    "user": {
      "id": 1,
      "name": "Alice",
      "email": "[email protected]",
      "posts": [
        { "title": "Hello", "content": "World" }
      ]
    }
  }
}

Query com variáveis

Variáveis parametrizam queries para que a mesma operação possa ser reutilizada com entradas diferentes. São declaradas no cabeçalho da operação com $name: Type. A string da query permanece estática; só o JSON de variáveis muda por chamada.

graphql
# Declare variables with operation name
query GetUser($id: ID!, $withPosts: Boolean!) {
  user(id: $id) {
    name
    posts @include(if: $withPosts) {
      title
    }
  }
}

# Variables sent alongside the query
{
  "id": "1",
  "withPosts": true
}

Básico de mutation

Mutations modificam dados e retornam um selection set como as queries. Por convenção, devem ser seguidas por uma leitura dos dados alterados. O GraphQL executa mutations em série (uma após a outra), enquanto campos de query rodam em paralelo.

graphql
# Mutation - write data, then return the result
mutation {
  createUser(input: { name: "Bob", email: "[email protected]" }) {
    id
    name
  }
}

# Response
{
  "data": {
    "createUser": {
      "id": "42",
      "name": "Bob"
    }
  }
}

Campos e selection sets

Um selection set é a lista de campos dentro das chaves. Scalars e enums retornam valores folha; tipos objeto exigem um selection set aninhado. Esquecer uma sub-seleção num tipo objeto é um erro de validação comum.

graphql
# You must select fields - GraphQL never returns whole objects
query {
  user(id: 1) {
    # this block is a "selection set"
    name
    email
  }
}

# Selecting a scalar returns its value directly
# Selecting an object REQUIRES a sub-selection set
query {
  user(id: 1) {
    name          # scalar - OK
    posts {       # object - needs { ... }
      title
    }
  }
}

GraphQL vs REST

REST expõe muitos endpoints com formas fixas; GraphQL expõe um único endpoint em que o cliente define a forma. Isso corta viagens de ida e volta e previne over/under-fetching. O trade-off é um servidor mais complexo e cache via POST.

graphql
# REST: multiple round trips, fixed shapes
GET /users/1            -> { id, name, email, address, ... }
GET /users/1/posts      -> [ { id, title, body, author, ... } ]

# GraphQL: one request, client-defined shape
query {
  user(id: 1) {
    name
    posts { title }
  }
}

# One endpoint, one POST request
POST /graphql
{ "query": "...", "variables": { ... } }

Introspecção

A introspecção permite que clientes descubram o schema em runtime. Ferramentas como GraphiQL, Apollo Studio e geradores de código dependem dela. Os campos raiz __schema e __type são os pontos de entrada. Servidores de produção podem desabilitar a introspecção para esconder detalhes internos.

graphql
# Ask the schema what types and fields it has
{
  __schema {
    types {
      name
      kind
    }
  }
}

# Inspect a specific type's fields
{
  __type(name: "User") {
    name
    fields {
      name
      type { name kind ofType { name kind } }
    }
  }
}
02

Schema e sistema de tipos

Declaração de schema

O bloco schema liga os tipos de operação raiz. Se seus tipos raiz se chamam Query, Mutation e Subscription, o Apollo/GraphQL.js infere o schema automaticamente e você pode omitir essa declaração por completo.

graphql
# SDL - Schema Definition Language
schema {
  query: Query
  mutation: Mutation
  subscription: Subscription
}

# In most servers the schema is inferred from the
# Query/Mutation/Subscription types, so this block is optional.

Tipos raiz

Query, Mutation e Subscription são os pontos de entrada de um schema. Query é o único tipo raiz obrigatório. Cada campo raiz vira uma operação que os clientes podem rodar. Nomeá-los como verbos (createUser) para mutations e substantivos para queries é a convenção.

graphql
type Query {
  user(id: ID!): User
  users(limit: Int = 10): [User!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

type Subscription {
  postAdded: Post!
}

Definições de tipo

Tipos são definidos com a palavra-chave type seguida de campos. Cada campo tem um nome e um tipo de retorno. O sufixo ! significa não nulo; [Type!] significa uma lista de itens não nulos; [Type!]! significa uma lista não nula de itens não nulos.

graphql
# Object type - the most common building block
type User {
  id: ID!
  name: String!
  age: Int
  email: String
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  author: User!
}

Adicionando descrições

Strings entre aspas triplas (ou strings de linha única antes de uma definição) viram parte do schema como descrições. Elas aparecem na documentação do GraphiQL e na introspecção. Comentários com # são só para dev e são removidos, então use strings com aspas triplas para documentação voltada ao usuário.

graphql
"""A registered user of the platform."""
type User {
  """The unique, immutable identifier."""
  id: ID!

  "Display name shown publicly."
  name: String!

  # plain # comments are NOT exposed to clients
  email: String
}

Schema com extensões

extend type adiciona campos a um tipo declarado em outro lugar. É assim que você divide um schema grande entre arquivos ou adiciona campos específicos de um módulo. Um tipo pode ser declarado uma vez e estendido muitas vezes, mas cada campo só pode ser definido uma vez.

graphql
# Extend an existing type without redefining it
type User {
  id: ID!
  name: String!
}

extend type User {
  age: Int
  posts: [Post!]!
}

# Useful for splitting a schema across files,
# or for adding fields only in certain modules.

Schema-first vs code-first

Schema-first escreve o SDL à mão e anexa resolvers (abordagem clássica do Apollo). Code-first constrói o schema programaticamente com decorators/builders de TypeScript (Nexus, TypeGraphQL, Pothos), ganhando segurança de tipos entre schema e resolvers. Ambos produzem o mesmo schema em runtime.

graphql
# 1) Schema-first: write SDL, bind resolvers
const typeDefs = `
  type Query { hello: String }
`;
const resolvers = { Query: { hello: () => "world" } };
const server = new ApolloServer({ typeDefs, resolvers });

# 2) Code-first: build with builders (Nexus, TypeGraphQL)
export const Query = queryType({
  definition(t) {
    t.string("hello", { resolve: () => "world" });
  },
});
03

Tipos scalar

Scalars embutidos

O GraphQL traz cinco scalars embutidos: Int, Float, String, Boolean e ID. ID é serializado como string, mas semanticamente significa um identificador — os clientes devem tratá-lo como opaco. Não há Date ou DateTime embutidos; você define esses por conta própria.

graphql
type Example {
  id: ID!          # unique identifier, serialized as string
  name: String!    # UTF-8 text
  age: Int         # 32-bit integer
  score: Float     # double-precision float
  active: Boolean! # true / false
}

Scalars personalizados

Scalars personalizados permitem representar primitivas do domínio. Depois de declará-los, você precisa fornecer um resolver que serialize (para JSON), interprete (de variáveis) e, opcionalmente, interprete literais (do AST inline). Caso contrário, o valor passa como está.

graphql
# Declare a custom scalar in SDL
scalar DateTime
scalar URL
scalar JSON

type Event {
  id: ID!
  at: DateTime!
  link: URL
  metadata: JSON
}

Resolvers de scalar

Um resolver de scalar tem três funções opcionais. serialize converte um valor interno para a saída JSON. parseValue converte uma entrada de variável para a forma interna. parseLiteral converte um literal inline no AST da query para a forma interna. Defina os três para um scalar totalmente tipado.

graphql
const resolvers = {
  DateTime: {
    // value -> JSON sent to client
    serialize: (value: Date) => value.toISOString(),
    // variable value -> internal value
    parseValue: (value: string) => new Date(value),
    // inline AST literal -> internal value
    parseLiteral: (ast) => {
      if (ast.kind === "StringValue") {
        return new Date(ast.value);
      }
      return null;
    },
  },
};

Scalar de Date/DateTime

O pacote graphql-scalars traz scalars testados em batalha: DateTime, Date, Time, EmailAddress, URL, UUID, BigInt, JSON e mais. Prefira-o a fazer à mão, especialmente para parse de datas ISO 8601, onde casos extremos abundam.

graphql
# Use graphql-scalars for well-tested common types
import { DateTimeResolver } from "graphql-scalars";

const resolvers = {
  DateTime: DateTimeResolver,
  Date: DateResolver,
  Time: TimeResolver,
};

# In SDL
scalar DateTime

type Query {
  now: DateTime!
}

Scalar JSON

Scalars JSON deixam dados arbitrários passar, úteis para config dinâmica ou metadados. O trade-off: você perde segurança de tipos e validação no nível do campo, e clientes não podem selecionar sub-campos. Use com parcimônia — um tipo objeto tipado é quase sempre melhor.

graphql
scalar JSON

type Query {
  # accept arbitrary JSON as input or output
  config: JSON
  setConfig(value: JSON): JSON
}

# The simplest pass-through resolver
const resolvers = {
  JSON: {
    serialize: (v) => v,
    parseValue: (v) => v,
    parseLiteral: (ast) => parseJsonLiteral(ast),
  },
};
04

Tipos objeto

Definindo tipos objeto

Um tipo objeto é uma coleção de campos nomeados com tipos de retorno. Tipos objeto formam o grafo — eles se referenciam para construir relacionamentos (User tem Posts, Post tem Author). Tipos objeto são tipos de saída; use input types para entradas.

graphql
type User {
  id: ID!
  name: String!
  email: String
  createdAt: String!
}

type Post {
  id: ID!
  title: String!
  body: String!
  published: Boolean!
}

Campos e tipos de campo

Cada campo declara um tipo de retorno. Anulável é o padrão; ! o torna não nulo. Listas envolvem com []. A posição do ! importa: [String] pode ser null e conter nulls; [String!] pode ser null, mas os itens não; [String!]! nunca pode ser null nem conter nulls.

graphql
type Product {
  id: ID!                # non-null ID
  name: String!          # non-null string
  price: Float!          # non-null float
  discount: Float        # nullable float
  tags: [String!]!       # non-null list of non-null strings
  reviews: [Review]      # nullable list of nullable reviews
}

Non-null e listas

A posição do ! controla a anulabilidade em cada nível. Non-null é poderoso, mas arriscado: se um resolver retorna null num campo não nulo, o erro se propaga e anula também o campo pai. Prefira anulável por padrão e opte por non-null onde um valor é realmente garantido.

graphql
type Example {
  a: [String]       # may be null; items may be null
  b: [String!]      # may be null; items NOT null
  c: [String]!      # NOT null; items may be null
  d: [String!]!     # NOT null; items NOT null

  name: String      # may be null
  name2: String!    # NOT null - errors if null returned
}

Objetos aninhados

Tipos objeto se referenciam para formar o grafo, habilitando queries que atravessam relacionamentos (user -> posts -> author -> profile). Referências circulares entre tipos são aceitáveis e comuns. O grafo é o que faz do GraphQL um grafo, não uma árvore de endpoints.

graphql
type User {
  id: ID!
  name: String!
  profile: Profile!
  posts: [Post!]!
}

type Profile {
  bio: String
  avatar: String
}

type Post {
  id: ID!
  title: String!
  author: User!   # back-reference creates the graph
}

Argumentos de campo em objetos

Qualquer campo — não apenas campos raiz — pode receber argumentos. Isso permite que um único tipo exponha visões filtradas/paginadas de dados relacionados (por exemplo, user.posts(limit: 10)). Argumentos com valores padrão tornam-se opcionais nas queries.

graphql
type User {
  id: ID!
  name: String!
  # an object field can take arguments
  posts(limit: Int = 5, after: ID): [Post!]!
  role(type: RoleType!): Role
}

type Query {
  user(id: ID!): User
}
05

Queries

Tipo Query

O tipo Query é o ponto de entrada de todas as leituras. Cada campo aqui é uma operação de nível superior que os clientes podem solicitar. Mantenha-o focado em leituras; coloque escritas na Mutation. Nomear campos como substantivos (users, user, search) é a convenção.

graphql
type Query {
  me: User!
  user(id: ID!): User
  users(limit: Int = 20, offset: Int = 0): [User!]!
  search(term: String!): [SearchResult!]!
}

# Clients run these as operations:
# query { me { name } }
# query { user(id: "1") { name } }

Múltiplos campos

Uma query pode selecionar múltiplos campos raiz numa única requisição. O GraphQL os executa em paralelo (exceto em mutations). Isso agrupa buscas relacionadas numa única viagem de ida e volta, uma vitória de eficiência importante sobre REST.

graphql
# Several fields in one request - executed in parallel
query {
  me { name email }
  user(id: "1") { name }
  users(limit: 3) { id name }
}

# Response contains all three under "data"
{
  "data": {
    "me": { "name": "Alice", "email": "[email protected]" },
    "user": { "name": "Bob" },
    "users": [ { "id": "1", "name": "Bob" }, ... ]
  }
}

Aliases

Aliases renomeiam campos na resposta. São obrigatórios ao selecionar o mesmo campo com argumentos diferentes — as chaves do objeto JSON precisam ser únicas. Aliases também são úteis para chaves de resposta mais curtas ou mais significativas.

graphql
# Same field twice with different args needs aliases
query {
  alice: user(id: "1") { name }
  bob:   user(id: "2") { name }
}

# Response keys match the aliases
{
  "data": {
    "alice": { "name": "Alice" },
    "bob":   { "name": "Bob" }
  }
}

Queries aninhadas

Atravessar relacionamentos é o superpoder do GraphQL. O cliente caminha pelo grafo (user -> posts -> comments -> author) numa única query. O servidor resolve cada campo via seu resolver; aninhamento profundo é aceitável, mas fique atento a consultas N+1 no backend.

graphql
query {
  user(id: "1") {
    name
    posts {            # traverse relationship
      title
      comments {        # and another level
        author {
          name
        }
      }
    }
  }
}

Query com argumentos

Argumentos podem ser literais inline ou variáveis. Literais inline servem para valores estáticos; use variáveis sempre que um valor vier de entrada do usuário ou mudar por chamada. Variáveis mantêm a query cacheável e evitam concatenação de strings.

graphql
# Schema
type Query {
  user(id: ID!, includeEmail: Boolean = false): User
}

# Inline arguments
query {
  user(id: "1", includeEmail: true) {
    name
    email
  }
}

# Prefer variables for dynamic values
query($uid: ID!, $withEmail: Boolean!) {
  user(id: $uid, includeEmail: $withEmail) {
    name
    email
  }
}

Nome da operação

Nomear operações (query GetUserProfile) é opcional, mas fortemente recomendado. Operações nomeadas são mais fáceis de depurar, aparecem em logs e no Apollo Studio, e são exigidas ao enviar múltiplas operações num documento ou para queries persistidas.

graphql
# Give operations a name - required in production
query GetUserProfile($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
  }
}
06

Mutations

Tipo Mutation

O tipo Mutation é o ponto de entrada das escritas. Por convenção, nomeie campos de mutation como verbos (createUser, updatePost). Mutations rodam em série, na ordem escrita, então efeitos colaterais dependentes de ordem são seguros entre múltiplos campos de mutation numa requisição.

graphql
type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
  createPost(input: CreatePostInput!): Post!
}

# Client mutation
mutation {
  createUser(input: { name: "Alice", email: "[email protected]" }) {
    id
    name
  }
}

Mutation com input

Use input types para argumentos de mutation. Eles agrupam campos relacionados, deixam a assinatura limpa e evoluem com segurança (adicione campos opcionais sem quebrar). Sempre passe payloads de mutation via variáveis, nunca literais inline.

graphql
input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

mutation($input: CreateUserInput!) {
  createUser(input: $input) {
    id
    name
  }
}

# { "input": { "name": "Bob", "email": "[email protected]" } }

Retornando payloads

Um padrão comum é um objeto payload envolvendo o resultado com errors, um flag de sucesso ou um client mutation ID. Isso é mais flexível que lançar erro — você pode retornar sucesso parcial e erros de validação estruturados junto com a entidade.

graphql
# Return the changed entity AND related fields like errors
type CreateUserPayload {
  user: User
  errors: [UserError!]!
}

type UserError {
  field: String
  message: String!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

Múltiplas mutations

Diferente das queries (paralelas), mutations numa mesma operação executam em série, na ordem declarada. Isso garante que a segunda mutation veja os efeitos da primeira. Se um campo de mutation falhar, os seguintes ainda rodam — valide as entradas e use transações quando necessário.

graphql
# Multiple mutations run SERIALLY in declared order
mutation {
  createPost(input: { title: "A" }) {
    id
  }
  publishPost(id: "1") {
    publishedAt
  }
}

Idempotência

Retentativas de rede podem duplicar escritas. Uma chave de idempotência permite que o servidor reconheça uma retentativa e retorne o resultado original em vez de criar uma duplicata. Essencial para pagamentos, pedidos e qualquer ação não reversível.

graphql
# Use a client mutation id or idempotency key
input CreateOrderInput {
  idempotencyKey: String!
  productId: ID!
  quantity: Int!
}

type Mutation {
  createOrder(input: CreateOrderInput!): Order!
}

# Clients retry with the SAME idempotencyKey on failure
# Server returns the original order instead of creating a duplicate
07

Subscriptions

Tipo Subscription

Subscriptions empurram dados do servidor para o cliente quando eventos ocorrem, tipicamente sobre WebSocket. São operações de longa duração. Mantenha os payloads pequenos — clientes costumam buscar dados detalhados com uma query posterior em vez de receber objetos grandes em streaming.

graphql
type Subscription {
  postAdded: Post!
  userJoined(roomId: ID!): User!
  messageReceived(userId: ID!): Message!
}

# Client subscribes (usually over WebSocket)
subscription {
  postAdded {
    id
    title
    author { name }
  }
}

Assinando eventos

Um resolver de subscription expõe uma função subscribe que retorna um AsyncIterator. Mutations (ou qualquer código do servidor) publicam eventos no mesmo tópico via pubsub. A função resolve opcional transforma o payload publicado na forma do campo.

graphql
# Server-side resolver with asyncIterator
const resolvers = {
  Subscription: {
    postAdded: {
      subscribe: () => pubsub.asyncIterator(["POST_ADDED"]),
      resolve: (payload) => payload.postAdded,
    },
  },
};

# Trigger from a mutation
const resolvers = {
  Mutation: {
    createPost: async (_, args, { pubsub }) => {
      const post = await createPost(args);
      await pubsub.publish("POST_ADDED", { postAdded: post });
      return post;
    },
  },
};

PubSub

O PubSub do graphql-subscriptions funciona para uma única instância de servidor. Para múltiplas instâncias atrás de um balanceador, você precisa de um broker compartilhado — redis-pubsub, MQTT ou um pubsub com Kafka — para que os eventos alcancem clientes conectados a qualquer instância.

graphql
import { PubSub } from "graphql-subscriptions";

const pubsub = new PubSub();

// publish an event
pubsub.publish("POST_ADDED", { postAdded: post });

// consume in a subscription resolver
subscribe: () => pubsub.asyncIterator(["POST_ADDED"])

# For multi-instance production, swap PubSub for
# Redis, NATS, or Kafka-based implementations.

Subscription com filtros

withFilter permite que cada cliente conectado receba apenas eventos relevantes — por exemplo, mensagens endereçadas a ele. A função de filtro recebe o payload publicado e as variáveis da subscription. Mantenha os filtros baratos; eles rodam para cada evento publicado por cliente conectado.

graphql
const resolvers = {
  Subscription: {
    messageReceived: {
      subscribe: withFilter(
        () => pubsub.asyncIterator(["MESSAGE_RECEIVED"]),
        (payload, variables) =>
          payload.messageReceived.recipientId === variables.userId
      ),
      resolve: (payload) => payload.messageReceived,
    },
  },
};

# Only events where the filter returns true reach this client

Transporte WebSocket

Subscriptions usam o protocolo graphql-ws (ou o legado subscriptions-transport-ws) sobre WebSocket. O protocolo mais novo graphql-ws é o recomendado. connectionParams transporta tokens de auth. O servidor precisa instalar o handler WS junto ao endpoint HTTP.

graphql
# Client uses graphql-ws over WebSocket
import { createClient } from "graphql-ws";

const wsClient = createClient({
  url: "ws://localhost:4000/graphql",
  connectionParams: { authToken: "..." },
});

wsClient.subscribe(
  { query: "subscription { postAdded { id title } }" },
  {
    next: (data) => console.log(data),
    error: (err) => console.error(err),
    complete: () => console.log("done"),
  }
);
08

Argumentos

Argumentos de campo

Argumentos são nomeados, nunca posicionais. Podem aparecer em qualquer campo, não apenas nos raiz. Argumentos nomeados tornam as queries autoexplicativas e independentes de ordem. Use variáveis em vez de literais inline quando os valores forem dinâmicos.

graphql
type Query {
  user(id: ID!): User
  posts(limit: Int, offset: Int): [Post!]!
}

# Arguments can be inline literals
query {
  user(id: "1") { name }
  posts(limit: 10, offset: 0) { title }
}

Valores padrão

Argumentos com valores padrão tornam-se opcionais — clientes podem omiti-los. Valores padrão são avaliados por requisição. Para argumentos não nulos não há default; o cliente precisa fornecer um valor. Defaults mantêm as queries concisas, permanecendo explícitos quando necessário.

graphql
type Query {
  # default values make arguments optional
  posts(limit: Int = 10, sort: String = "newest"): [Post!]!
  user(id: ID!, includeDeleted: Boolean = false): User
}

# These are equivalent:
query { posts { title } }
query { posts(limit: 10, sort: "newest") { title } }

Tipos de argumento

Argumentos podem ser scalars, enums, listas ou input object types — nunca tipos objeto regulares (esses são apenas de saída). Input objects são a forma idiomática de passar argumentos complexos e estruturados, especialmente para filtros e paginação.

graphql
type Query {
  # scalar arguments
  byId(id: ID!): User
  byAge(min: Int!, max: Int!): [User!]!

  # enum argument
  byStatus(status: UserStatus!): [User!]!

  # input object argument
  search(filter: UserFilter!): [User!]!

  # list argument
  byIds(ids: [ID!]!): [User!]!
}

Obrigatório vs opcional

O sufixo ! num argumento o torna obrigatório. Omitir um argumento obrigatório falha a validação antes de o resolver rodar, retornando um erro claro. Prefira obrigatório para entradas genuinamente necessárias e opcional-com-default para comportamento ajustável.

graphql
type Query {
  # required (non-null) - client MUST provide
  user(id: ID!): User

  # optional (nullable) - client may omit
  posts(limit: Int): [Post!]!

  # optional with default
  recentPosts(limit: Int = 5): [Post!]!
}

# Omitting a required argument is a validation error
# before any resolver runs.

Argumentos de lista

Argumentos de lista usam colchetes. [ID!]! significa uma lista não nula de IDs não nulos — o cliente precisa passar uma lista e cada elemento deve ser não nulo. Passe listas via variáveis em vez de literais inline, por limpeza e para evitar problemas de escape.

graphql
type Query {
  usersByIds(ids: [ID!]!): [User!]!
  tags(allOf: [String!]): [Post!]!
}

# Inline list literal
query {
  usersByIds(ids: ["1", "2", "3"]) { name }
}

# Via variable
query($ids: [ID!]!) {
  usersByIds(ids: $ids) { name }
}
# { "ids": ["1", "2", "3"] }
09

Variáveis

Definição de variável

Variáveis parametrizam operações. Declare-as como $name: Type no cabeçalho da operação, referencie-as como $name no corpo, e envie os valores num campo JSON de variables separado. Isso separa a query estática dos dados dinâmicos.

graphql
# Declare variables in the operation, then use them
query GetUser($id: ID!) {
  user(id: $id) {
    name
    email
  }
}

# Variables are sent in a separate JSON object
{
  "id": "1"
}

Tipos de variável

Os tipos das variáveis devem corresponder aos tipos dos argumentos no schema. Variáveis podem ser anuláveis, não nulas, listas ou input objects. O tipo de uma variável deve ser um input type (scalar, enum ou input object) — nunca um tipo objeto de saída.

graphql
query Search(
  $term: String!
  $limit: Int = 10
  $filters: PostFilter
  $tags: [String!]
) {
  search(term: $term, limit: $limit, filters: $filters, tags: $tags) {
    title
  }
}

Valores padrão

Defaults de variável aplicam quando o cliente omite a variável. Só são legais em variáveis anuláveis — uma variável não nula significa que o cliente DEVE fornecer um valor. Defaults permitem que clientes enviem conjuntos mínimos de variáveis enquanto os servidores permanecem flexíveis.

graphql
query Posts($limit: Int = 10, $sort: String = "newest") {
  posts(limit: $limit, sort: $sort) { title }
}

# If the client omits "limit", it defaults to 10.
# Only nullable variables can have defaults - a non-null
# variable with a default is a contradiction.

Variáveis obrigatórias

Uma variável não nula (!) é obrigatória — omiti-la falha a validação antes de o resolver rodar. Essa é a forma mais segura de garantir que uma entrada exista. Variáveis não nulas não podem ter defaults; se quiser um default, torne a variável anulável.

graphql
query User($id: ID!) {     # ! means required
  user(id: $id) { name }
}

# Missing required variable -> validation error
{ "id": "1" }      # OK
{ }                # ERROR: variable $id of type ID! is required

# A non-null variable cannot have a default value.

Variáveis com diretivas

Variáveis podem dirigir diretivas como @include e @skip, permitindo que clientes alternem campos dinamicamente. Ótimo para feature flags, testes A/B ou seções condicionais — tudo com um único documento de query cacheado.

graphql
query User($id: ID!, $withPosts: Boolean!) {
  user(id: $id) {
    name
    posts @include(if: $withPosts) {
      title
    }
  }
}

# { "id": "1", "withPosts": false }  -> posts omitted
# { "id": "1", "withPosts": true }   -> posts included
10

Fragments

Fragments nomeados

Fragments são selection sets reutilizáveis vinculados a um tipo específico (fragment Name on Type). Espalhe-os com ...Name onde quer que aquele tipo apareça. Mantêm as queries DRY e permitem que clientes compartilhem seleções de campo entre operações.

graphql
# Define a reusable fragment
fragment UserFields on User {
  id
  name
  email
}

# Spread it into queries
query {
  user(id: "1") {
    ...UserFields
  }
  users {
    ...UserFields
  }
}

Composição de fragments

Fragments podem espalhar outros fragments, construindo seleções compostas. Isso modulariza as escolhas de campos (perfil básico vs completo) e permite que componentes de UI declarem cada um suas necessidades de dados, e depois os componham numa única query.

graphql
fragment UserBasic on User {
  id
  name
}

fragment UserWithEmail on User {
  ...UserBasic
  email
}

fragment UserFull on User {
  ...UserWithEmail
  posts { title }
}

# Fragments can spread other fragments of the same type.

Variáveis de fragment

Variáveis de fragment estilo Relay permitem que um fragment aceite parâmetros (como um limit) que quem chama passa via @arguments. Isso torna os fragments verdadeiramente reutilizáveis com configurações diferentes. O Apollo suporta isso via a diretiva @arguments das diretivas de cliente dele.

graphql
fragment UserPosts on User
  @argumentDefinitions(limit: { type: "Int", defaultValue: 5 }) {
  posts(limit: $limit) {
    title
  }
}

query {
  user(id: "1") {
    ...UserPosts @arguments(limit: 10)
  }
}

# @argumentDefinitions and @arguments come from
# Relay; Apollo uses a similar pattern via client directives.

Fragments reutilizáveis

Colocar fragments junto dos componentes que os renderizam é um padrão poderoso: cada componente declara suas necessidades de dados, e o pai os compõe numa única query. Isso escala a busca de dados em apps grandes (Relay e Apollo ambos suportam).

graphql
// Colocate fragments with the UI component that uses them
const USER_CARD = graphql`
  fragment UserCard_user on User {
    id
    name
    avatarUrl
  }
`;

function UserCard({ user }) {
  return <div>{user.name}</div>;
}

// The parent query spreads all needed fragments
query {
  users {
    ...UserCard_user
  }
}

Ressalvas de fragments

Um fragment declarado em Post só pode ser espalhado onde um Post é esperado — espalhá-lo num User é um erro de validação. Use inline fragments com condições de tipo para espalhar condicionalmente em unions/interfaces. Evite também espalhamentos circulares de fragments.

graphql
# A fragment must match the type where it's spread
fragment PostFields on Post { title body }

query {
  user(id: "1") {
    ...PostFields   # ERROR: user is not a Post
  }
}

# Fragments can only spread on the declared type
# (or via type conditions with inline fragments).
11

Inline fragments

Básico do inline fragment

Um inline fragment é um selection set sem nome, prefixado com ... on Type. Aplica os campos apenas quando o objeto em runtime corresponde à condição de tipo. É assim que se acessam campos específicos de tipo em interfaces e unions.

graphql
# An inline fragment is a selection set with a type condition
query {
  user(id: "1") {
    id
    name
    # fields common to User
    ... on AdminUser {
      permissions
    }
  }
}

# No name - declared inline in the query.

Condições de tipo

A sintaxe ... on Type é uma condição de tipo. Múltiplos inline fragments numa seleção permitem tratar cada tipo possível de uma union/interface separadamente. Campos compartilhados pelos tipos podem ser selecionados diretamente fora dos fragments.

graphql
query Search($term: String!) {
  search(term: $term) {
    ... on User { name email }
    ... on Post { title author { name } }
    ... on Comment { body }
  }
}

Acesso a unions

Unions não têm campos compartilhados além de __typename, então para ler dados específicos de tipo você precisa de inline fragments. __typename é sempre selecionável e diz ao cliente qual o tipo concreto de cada item — essencial para renderizar resultados de union.

graphql
union SearchResult = User | Post | Comment

query {
  search(term: "graphql") {
    # shared __typename is always available
    __typename
    ... on User { name }
    ... on Post { title }
    ... on Comment { body }
  }
}

Acesso a interfaces

Interfaces declaram campos compartilhados. Esses campos podem ser selecionados diretamente na interface; campos específicos de tipo precisam de inline fragments. Diferente de unions, interfaces garantem um conjunto comum de campos que cada tipo implementador deve fornecer.

graphql
interface Node { id: ID! }
type User implements Node { id: ID! name: String! }
type Post implements Node { id: ID! title: String! }

query {
  node(id: "1") {
    id              # shared interface field - selectable directly
    ... on User { name }
    ... on Post { title }
  }
}

Fragment nomeado com condição de tipo

Fragments nomeados carregam sua própria condição de tipo, então você pode espalhá-los num resultado de union/interface e cada um se aplica apenas ao seu tipo correspondente. Isso combina reutilização com seleção condicional — espalhe vários fragments nomeados para cobrir os membros da union.

graphql
# Named fragments can also carry a type condition
fragment UserFields on User { name email }
fragment PostFields on Post { title }

query {
  search(term: "a") {
    ...UserFields
    ...PostFields
  }
}

# Equivalent to inlining those fragments inline.
12

Diretivas

Diretivas embutidas

O GraphQL traz duas diretivas de cliente embutidas: @skip(if: Boolean!) omite o campo quando true, @include(if: Boolean!) o inclui apenas quando true. São mutuamente exclusivas e podem ser aplicadas a campos, fragment spreads e inline fragments.

graphql
# @skip - omit field if true
query($skip: Boolean!) {
  user(id: "1") {
    name
    email @skip(if: $skip)
  }
}

# @include - include field only if true
query($withPosts: Boolean!) {
  user(id: "1") {
    posts @include(if: $withPosts) { title }
  }
}

@skip e @include

@skip e @include permitem que uma query sirva múltiplas formas. Recebem uma variável Boolean, então a mesma query persistida pode renderizar um resumo ou uma visão detalhada conforme as variáveis — sem precisar manter duas strings de query.

graphql
query User($id: ID!, $detailed: Boolean!) {
  user(id: $id) {
    name
    email @skip(if: $detailed)      # hide when detailed
    profile @include(if: $detailed) {  # show when detailed
      bio
    }
  }
}

# { "id": "1", "detailed": false } -> name, email
# { "id": "1", "detailed": true }  -> name, profile { bio }

Diretivas personalizadas

Diretivas personalizadas começam com uma declaração directive, que dá argumentos e locais permitidos. A semântica de execução não é embutida — você as implementa com schema transforms (Apollo) ou directive visitors (graphql-tools). Usos comuns: @auth, @cached, @deprecated.

graphql
# Declare a directive in SDL
directive @auth(requires: Role = ADMIN) on FIELD_DEFINITION

type Query {
  adminData: String @auth(requires: ADMIN)
  userData: String @auth(requires: USER)
}

# A directive needs a location: FIELD_DEFINITION, FIELD,
# OBJECT, ENUM, etc. Logic is implemented in the server
# (e.g. via schema transforms or a directive visitor).

Locais de diretiva

Toda diretiva declara onde é legal usá-la — em operações, campos, fragments ou definições de schema (FIELD_DEFINITION, OBJECT etc.). Diretivas de cliente (aplicadas em queries) e diretivas de schema (aplicadas em SDL) usam conjuntos de locais diferentes. Valide na construção do schema.

graphql
# Where a directive can appear
directive @example on
  | QUERY          # operation
  | FIELD          # a field in a selection
  | FRAGMENT_DEFINITION
  | FRAGMENT_SPREAD
  | INLINE_FRAGMENT
  | FIELD_DEFINITION  # in SDL (server-side)
  | OBJECT | INTERFACE | UNION | ENUM
  | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION;

# Multiple locations use | between them.

Argumentos de diretiva

Diretivas podem receber argumentos tipados com defaults. A embutida @deprecated(reason:) marca campos e valores de enum como obsoletos; ferramentas avisam clientes que os usam. Diretivas personalizadas com argumentos dirigem comportamentos como TTLs de cache ou papéis exigidos.

graphql
directive @deprecated(
  reason: String = "No longer supported"
) on FIELD_DEFINITION | ENUM_VALUE

type Query {
  oldField: String @deprecated(reason: "Use newField")
  newField: String
}

enum Status {
  ACTIVE
  INACTIVE @deprecated(reason: "Use ARCHIVED")
  ARCHIVED
}
13

Enums

Definindo enums

Um enum é um conjunto finito de valores nomeados. Enums são tipos scalar — são valores folha, sem sub-seleções. Use-os para qualquer campo com um conjunto fixo de opções (status, role, kind) em vez de strings mágicas, ganhando validação e autoexplicação.

graphql
enum Role {
  ADMIN
  USER
  GUEST
}

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

type User {
  role: Role!
}

type Post {
  status: PostStatus!
}

Valores de enum

Valores de enum são escritos como identificadores sem aspas nas queries (color: RED), mas serializados como strings em variáveis JSON e respostas. A convenção de nomes é UPPER_SNAKE_CASE. O servidor valida qualquer valor contra o conjunto declarado.

graphql
enum Color {
  RED
  GREEN
  BLUE
}

# In a query, enum values are unquoted identifiers
query {
  products(color: RED) { name }
}

# In variables JSON, they're sent as strings
{ "color": "RED" }

Enums em queries

Enums funcionam tanto como tipos de campo quanto como tipos de argumento. Usado como argumento, o cliente passa um dos valores declarados. Valores de enum inválidos falham a validação antes de o resolver rodar, dando erros claros.

graphql
type Query {
  posts(status: PostStatus!): [Post!]!
}

query {
  posts(status: PUBLISHED) { title }
}

query($status: PostStatus!) {
  posts(status: $status) { title }
}
# { "status": "DRAFT" }

Resolvers de enum

Por padrão, um valor de enum mapeia para si mesmo. Um resolver de enum permite mapear entre o nome público da API (ADMIN) e uma representação interna (a string "admin" ou um código numérico de papel). Isso desacopla seu schema dos detalhes de armazenamento.

graphql
# Map internal values <-> API values
enum Role {
  ADMIN
  USER
}

const resolvers = {
  Role: {
    ADMIN: "admin",   // internal DB value
    USER: "user",
  },
};

# Internally the resolver sees "admin"; the client sees ADMIN.
# Useful when DB values differ from the public API.

Boas práticas de enum

Sempre prefira enums a strings livres para conjuntos fixos de opções — eles validam entradas, documentam a API e habilitam ferramentas melhores. Para remover um valor de enum sem quebrar clientes, descontinue-o primeiro. Remover um valor que clientes ainda enviam é uma mudança que quebra compatibilidade.

graphql
# Prefer enums over strings for fixed option sets
type User {
  role: Role!          # GOOD - validated, self-documenting
  roleStr: String      # AVOID - no validation, magic strings
}

# Deprecate values instead of removing them
enum Status {
  ACTIVE
  INACTIVE @deprecated(reason: "Use ARCHIVED")
  ARCHIVED
}
14

Interfaces

Definindo interfaces

Uma interface é um tipo abstrato que declara um conjunto de campos que os tipos implementadores devem fornecer. Ela define um contrato. Interfaces são úteis para abstrações compartilhadas como Node (IDs globais estilo relay) ou Character entre tipos relacionados.

graphql
interface Node {
  id: ID!
}

interface Character {
  name: String!
}

type User implements Node & Character {
  id: ID!
  name: String!
  email: String!
}

Implementando interfaces

Um tipo declara que implementa uma interface com a palavra-chave implements. Deve definir os campos que a interface declara, com tipos compatíveis. Um tipo pode implementar múltiplas interfaces (separadas por &). O schema valida isso em tempo de construção.

graphql
interface Node {
  id: ID!
}

type User implements Node {
  id: ID!        # required by Node
  name: String!
}

type Post implements Node {
  id: ID!        # required by Node
  title: String!
}

# A type must implement every field of the interface.

Consultando interfaces

Quando um campo retorna uma interface, você pode selecionar os campos compartilhados da interface diretamente. Para acessar campos específicos de tipo, use inline fragments (... on User). O tipo em runtime de cada resultado determina quais inline fragments se aplicam.

graphql
interface Node { id: ID! }

type Query {
  node(id: ID!): Node
}

query {
  node(id: "1") {
    id              # interface field - always selectable
    ... on User { name }
    ... on Post { title }
  }
}

Resolvers de interface

Uma interface precisa de uma função __resolveType que retorna o nome do tipo concreto (ou o objeto de tipo) para um dado valor em runtime. É assim que o GraphQL sabe quais inline fragments aplicar. Sem ela, o GraphQL não consegue determinar o tipo concreto em runtime.

graphql
interface Character { name: String! }

type Human implements Character {
  name: String!
  starships: [String!]!
}

type Droid implements Character {
  name: String!
  primaryFunction: String
}

const resolvers = {
  Character: {
    // tell GraphQL which concrete type a value is
    __resolveType(obj) {
      return obj.primaryFunction ? "Droid" : "Human";
    },
  },
};

Múltiplas interfaces

Um tipo pode implementar múltiplas interfaces com o separador &. Isso compõe capacidades — por exemplo, um Article que é Node, Timestamped e SoftDeletable. A consulta retorna o tipo da interface, e clientes usam inline fragments para campos concretos.

graphql
interface Node { id: ID! }
interface Timestamped { createdAt: String! }
interface SoftDeletable { deletedAt: String }

type Article implements Node & Timestamped & SoftDeletable {
  id: ID!
  createdAt: String!
  deletedAt: String
  title: String!
}

# Use & to list multiple implemented interfaces.
15

Unions

Definindo unions

Uma union é um tipo abstrato que pode ser um de vários tipos concretos, sem exigir campos compartilhados (diferente de interfaces). Defina-a com union Name = TypeA | TypeB. Unions são ótimas quando os resultados são heterogêneos, mas conceitualmente relacionados.

graphql
union SearchResult = User | Post | Comment

type User { id: ID! name: String! }
type Post { id: ID! title: String! }
type Comment { id: ID! body: String! }

type Query {
  search(term: String!): [SearchResult!]!
}

Union vs interface

Use uma interface quando os membros compartilham um contrato comum (campos que cada membro tem). Use uma union quando os membros não se relacionam exceto conceitualmente — não compartilham campos. Um tipo pode estar em muitas unions; unions não podem implementar outras unions diretamente.

graphql
# INTERFACE - shared contract
interface Node { id: ID! }
type User implements Node { id: ID! name: String! }
type Post implements Node { id: ID! title: String! }
# All members share the "id" field.

# UNION - no shared contract
union SearchResult = User | Post
# Members share NO required fields.

Consultando unions

Unions não expõem campos próprios, então você precisa de inline fragments para ler qualquer coisa. __typename está sempre disponível e diz ao cliente qual o tipo concreto de cada item. Selecionar um campo diretamente numa union (sem condição de tipo) é um erro de validação.

graphql
query {
  search(term: "graphql") {
    __typename          # always available
    ... on User { name email }
    ... on Post { title }
    ... on Comment { body }
  }
}

# You CANNOT select fields directly on a union
# (no shared fields) - only via inline fragments.

Resolvers de union

Como interfaces, unions precisam de um resolver __resolveType que retorne o nome do tipo concreto para um valor em runtime. Sem ele, o GraphQL não consegue escolher inline fragments. Retorne o nome do tipo como string ou o objeto de tipo do schema.

graphql
union SearchResult = User | Post | Comment

const resolvers = {
  SearchResult: {
    __resolveType(obj) {
      if (obj.email) return "User";
      if (obj.title) return "Post";
      if (obj.body) return "Comment";
      return null;
    },
  },
};

Padrões comuns

Unions modelam resultados de sucesso-ou-erro: uma mutation retorna uma union de um tipo de sucesso e um tipo de erro, forçando clientes a tratar ambos. É mais seguro em tipos que um único payload com campos de erro opcionais. (O SDL exige union, não aliases de tipo.)

graphql
# Mutation result that may be success or error
type CreateUserSuccess { user: User! }
type CreateUserError { messages: [String!]! }
type CreateUserPayload = CreateUserSuccess | CreateUserError
# (note: a type alias like this isn't valid SDL; use union)
union CreateUserPayload = CreateUserSuccess | CreateUserError

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}
16

Input types

Input object types

Input types são tipos objeto usados como argumentos, declarados com input. Agrupam campos relacionados (um usuário, um filtro) num único argumento. Diferente dos tipos objeto de saída, input types só podem conter input types (scalars, enums, outros input types).

graphql
input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

mutation($input: CreateUserInput!) {
  createUser(input: $input) { id }
}
# { "input": { "name": "Alice", "email": "[email protected]" } }

Input vs output

Tipos de saída (type) podem ter argumentos de campo e resolvers; input types (input) são portadores de dados puros, sem resolvers. São namespaces separados — você pode ter um tipo User e um input UserInput. Não reutilize um para ambos; isso quebra a evolução.

graphql
# OUTPUT type - returned from resolvers, has resolvers
type User {
  id: ID!
  name: String!
  posts: [Post!]!   # can have field arguments and resolvers
}

# INPUT type - passed into operations, no resolvers
input UserInput {
  name: String!
  email: String!
  # NO field arguments, NO resolvers, NO output object types
}

# A type cannot be used as both input and output.

Inputs aninhados

Input types podem referenciar outros input types e listas, modelando payloads aninhados complexos. Ideal para formulários hierárquicos ou filtros aninhados. Cada nível é validado contra o schema, dando erros claros em entradas malformadas.

graphql
input AddressInput {
  street: String!
  city: String!
  zip: String!
}

input CreateUserInput {
  name: String!
  email: String!
  address: AddressInput      # nested input type
  tags: [String!]            # list input
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

Defaults de input

Campos e argumentos de input podem ter valores padrão. Quando o cliente omite um campo, o default se aplica. Defaults tornam as entradas opcionais sem forçar clientes a enviar objetos completos. Note que defaults são literais estáticos, não computados por requisição.

graphql
input PaginationInput {
  limit: Int = 20
  offset: Int = 0
  sort: SortOrder = DESC
}

enum SortOrder { ASC DESC }

type Query {
  posts(page: PaginationInput = { limit: 20, offset: 0 }): [Post!]!
}

# Defaults apply per-field when omitted by the client.

Validação de input

O GraphQL valida tipos e não-nulidade, mas não regras semânticas (formato de e-mail, faixa de idade, comprimento de string). Implemente-as no resolver, lançando UserInputError para dados inválidos. Alguns servidores adicionam diretivas de validação (@constraint) para regras declarativas.

graphql
input CreateUserInput {
  name: String!              # required, non-null
  email: String!             # format check needs custom code
  age: Int                   # range check needs custom code
}

# GraphQL validates structure; you validate semantics
function createUser(_, { input }) {
  if (!input.email.includes("@")) {
    throw new UserInputError("Invalid email");
  }
  if (input.age < 0 || input.age > 150) {
    throw new UserInputError("Invalid age");
  }
  // ...
}
17

Resolvers

Funções resolver

Um resolver é uma função que produz o valor de um campo. O mapa de resolvers espelha o schema: resolvers.Query.user trata o campo user. Se um resolver estiver ausente, o GraphQL usa um padrão que lê a propriedade correspondente do pai.

graphql
const resolvers = {
  Query: {
    user: (parent, args, context, info) => {
      return context.db.user.findById(args.id);
    },
    users: () => db.users.findAll(),
  },
  Mutation: {
    createUser: (_, { input }, { db }) =>
      db.user.create(input),
  },
};

Argumentos do resolver

Cada resolver recebe quatro argumentos: parent (o valor resolvido do campo pai), args (os argumentos deste campo), context (um objeto compartilhado por requisição) e info (AST e metadados de execução). Os dois primeiros são os mais comuns; info serve para casos avançados como inspeção de sub-seleção.

graphql
// (parent, args, context, info)
const resolvers = {
  Query: {
    user: (parent, args, context, info) => {
      // parent   - value returned by the parent field (root for Query)
      // args     - arguments passed to this field
      // context  - shared per-request object (db, user, loaders)
      // info     - AST + execution info (rarely needed)
      return context.db.user.findById(args.id);
    },
  },
};

Cadeia de resolvers

Resolvers rodam numa cadeia depth-first: o resolver do campo pai produz um objeto, e o resolver de cada campo filho roda com esse objeto como parent. Esse fluxo de cima para baixo permite que cada campo resolva de forma independente — o grafo se monta campo por campo.

graphql
# query { user(id: "1") { name posts { title } } }
const resolvers = {
  Query: {
    user: () => ({ id: "1", name: "Alice" }),   // runs first
  },
  User: {
    posts: (user, args, ctx) => {                // runs after user
      return ctx.db.posts.findByAuthor(user.id);
    },
  },
  Post: {
    title: (post) => post.title,                 // runs after posts
  },
};

Resolvers assíncronos

Resolvers podem retornar Promises; o GraphQL as aguarda antes de continuar para os campos filhos. É assim que se chamam bancos de dados e APIs. Use async/await por legibilidade. Resolvers no mesmo nível rodam em paralelo (para queries), então trabalho assíncrono independente se agrupa naturalmente.

graphql
const resolvers = {
  Query: {
    // return a Promise - GraphQL awaits it
    user: async (_, { id }, { db }) => {
      const user = await db.user.findById(id);
      if (!user) throw new Error("User not found");
      return user;
    },
  },
  User: {
    posts: async (user, _, { db }) =>
      db.posts.findByAuthor(user.id),
  },
};

Resolvers padrão

Se um campo não tem resolver, o GraphQL lê a propriedade de mesmo nome do objeto pai (retornando null se undefined). Você só escreve resolvers para campos que precisam de lógica ou busca. O comportamento padrão funciona quando seus objetos pai já têm a forma certa.

graphql
# If you don't define a resolver, GraphQL reads from the parent
const resolvers = {
  User: {
    // name resolver missing - default behavior:
    // (parent) => parent.name
    posts: (user) => fetchPosts(user.id),  // only this is custom
  },
};

// Equivalent explicit default:
User: {
  name: (user) => (user.name === undefined ? null : user.name),
}

Boas práticas de resolver

Mantenha os resolvers enxutos: delegue a busca a classes de fonte de dados no context. Isso centraliza o acesso a dados (testável, mockável) e permite que fontes de dados agrupem e cacheiem. Resolvers devem orquestrar, não conter SQL ou lógica de fetch diretamente.

graphql
# Keep resolvers thin - delegate to data sources
const resolvers = {
  Query: {
    user: (_, { id }, { dataSources }) =>
      dataSources.userAPI.getUser(id),
  },
  User: {
    posts: (user, _, { dataSources }) =>
      dataSources.postAPI.byAuthor(user.id),
  },
};

// dataSources live on context, are injected per request,
// and can batch/cache calls internally.
18

Context e DataLoader

Objeto context

O context é um objeto por requisição compartilhado pelos resolvers numa operação. Coloque aqui as dependências compartilhadas: clientes de banco de dados, o usuário autenticado, data loaders e loggers. A função de context roda uma vez por requisição, e seu valor de retorno é passado a cada resolver.

graphql
const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: ({ req }) => ({
    db: new PrismaClient(),
    user: getUserFromToken(req.headers.authorization),
    loaders: buildLoaders(),
  }),
});

// Inside any resolver, the third argument is context:
(parent, args, context) => context.db.user.findById(args.id);

Context por requisição

Crie instâncias novas de DataLoader dentro da função de context para que seus caches tenham escopo numa única requisição. Reutilizar um loader entre requisições vazaria dados em cache entre usuários. O próprio context é construído uma vez por requisição, então configuração por requisição vai aqui.

graphql
const context = async ({ req }) => {
  const token = req.headers.authorization || "";
  const user = await verifyToken(token);  // may be null

  return {
    user,
    db,
    // a FRESH DataLoader instance per request
    // so caches don't leak across requests
    userLoader: new DataLoader((ids) => batchGetUsers(ids)),
  };
};

O problema N+1

O problema N+1: buscar uma lista de N itens e depois fazer uma consulta extra por item para carregar um relacionamento. A resolução paralela de campos do GraphQL facilita cair nisso — um resolver User.posts roda uma vez por usuário. O resultado é uma enxurrada de consultas redundantes.

graphql
# query { users { id name posts { title } } }
// BAD: 1 query for users, then N queries for each user's posts
const resolvers = {
  User: {
    posts: (user, _, { db }) =>
      db.posts.findByAuthor(user.id),  // runs once per user!
  },
};

// If there are 100 users, that's 101 DB queries.
// This is the classic N+1 problem.

Básico do DataLoader

DataLoader combina muitas buscas individuais numa única requisição em lote. Você fornece uma função de lote que recebe um array de chaves e retorna um array de resultados na mesma ordem. O DataLoader então coleta todas as buscas dentro de um tick e chama sua função de lote uma vez.

graphql
import DataLoader from "dataloader";

// A batch function receives an array of keys, returns
// an array of values IN THE SAME ORDER as the keys.
const userLoader = new DataLoader(async (userIds) => {
  const users = await db.users.findMany({ where: { id: { in: userIds } } });
  // reorder to match the input keys
  return userIds.map((id) =>
    users.find((u) => u.id === id) ?? null
  );
});

DataLoader nos resolvers

Use loader.load(key) nos resolvers em vez de chamadas diretas ao DB. Dentro de um único tick, todas as buscas do mesmo loader são agrupadas numa única consulta, e os resultados ficam em cache pela duração da requisição. Isso mata os N+1 mantendo os resolvers simples.

graphql
const resolvers = {
  User: {
    posts: (user, _, { loaders }) =>
      loaders.postLoader.load(user.id),
  },
  Post: {
    author: (post, _, { loaders }) =>
      loaders.userLoader.load(post.authorId),
  },
};

// 100 users -> ONE batched query for all their posts,
// instead of 100 separate queries.

Batching e caching

DataLoader faz duas coisas: batching (muitas buscas num único tick do event loop viram uma chamada de lote) e cache por chave (buscas repetidas da mesma chave retornam a mesma Promise). O cache é por instância de loader, que é por que você cria um loader novo por requisição.

graphql
// Batching: many .load() calls in one tick -> one batch fn call
await Promise.all([loader.load(1), loader.load(2), loader.load(3)]);
// -> batchGetUsers([1, 2, 3]) called ONCE

// Caching: repeated .load(sameKey) returns the cached Promise
loader.load(1); loader.load(1); loader.load(1);
// -> batchGetUsers([1]) called ONCE; later calls hit cache

// .clear(key) invalidates; .clearAll() resets everything.
19

Tratamento de erros

Formato da resposta de erro

Erros são retornados num array errors de nível superior junto com data. Cada erro tem uma message, a localização na query, o path até o campo que falhou e extensions para códigos legíveis por máquina. Um erro de campo anula aquele campo (ou se propaga se non-null) enquanto data ainda retorna as partes bem-sucedidas.

graphql
# Errors appear in a top-level "errors" array
{
  "errors": [
    {
      "message": "User not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["user"],
      "extensions": {
        "code": "NOT_FOUND",
        "exception": { "stacktrace": ["..."] }
      }
    }
  ],
  "data": { "user": null }
}

Lançando erros

O tratamento de erros mais simples: lance um Error. O GraphQL o captura, anula o campo e adiciona uma entrada ao array errors. Para mais estrutura, use classes de erro especializadas (ApolloError, UserInputError) que carregam um código de erro em extensions.

graphql
const resolvers = {
  Query: {
    user: async (_, { id }, { db }) => {
      const user = await db.user.findById(id);
      if (!user) {
        throw new Error("User not found");
      }
      return user;
    },
  },
};

# Thrown errors become entries in the "errors" array.

Erros personalizados

Use classes de erro tipadas para transmitir intenção: UserInputError para entrada inválida do cliente (4xx), AuthenticationError para auth ausente, ForbiddenError para falta de permissão, e ApolloError com um código para casos personalizados. O código em extensions permite que clientes ramifiquem de forma confiável sobre erros.

graphql
import { ApolloError, UserInputError } from "apollo-server-errors";

const resolvers = {
  Mutation: {
    createUser: (_, { input }) => {
      if (!isValidEmail(input.email)) {
        throw new UserInputError("Invalid email", {
          field: "email",
        });
      }
      if (emailTaken(input.email)) {
        throw new ApolloError("Email taken", "EMAIL_TAKEN", {
          email: input.email,
        });
      }
      // ...
    },
  },
};

Extensions de erro

extensions carrega dados legíveis por máquina: uma string de código estável, dicas de retentativa, caminhos de campos de validação etc. Clientes devem ramificar sobre extensions.code em vez de interpretar a mensagem humana, que pode mudar. Mantenha stacktraces fora das respostas de produção.

graphql
# Structured, machine-readable error data
throw new ApolloError("Rate limited", "RATE_LIMITED", {
  code: "RATE_LIMITED",
  retryAfter: 60,
  limit: 100,
});

# Clients check extensions.code to handle errors
if (err.extensions.code === "RATE_LIMITED") {
  wait(err.extensions.retryAfter);
}

Resultados parciais

O GraphQL retorna resultados parciais: campos bem-sucedidos voltam em data, enquanto campos que falharam ficam null (ou se propagam se non-null) e são listados em errors. Prefira campos anuláveis para que uma falha não anule a resposta inteira. Non-null é um contrato forte — use-o deliberadamente.

graphql
# A non-null field error nulls the parent; nullable just nulls the field
type Query {
  user(id: ID!): User       # nullable - error nulls only "user"
  me: User!                 # non-null - error bubbles up to null "me"
}

# Query selecting multiple fields:
query { me { name } user(id: "bad") { name } }
# If "user" errors but "me" succeeds:
{
  "data": { "me": { "name": "Alice" }, "user": null },
  "errors": [{ "path": ["user"], "message": "..." }]
}
20

Apollo Server e integração

Configuração do Apollo Server

Apollo Server é o servidor GraphQL Node.js mais popular. Passe typeDefs (SDL) e resolvers para construí-lo, e depois inicie com o servidor standalone para dev rápido. Para produção, integre com um framework HTTP existente (Express, Fastify, Next.js) em vez do standalone.

graphql
import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";

const typeDefs = `#graphql
  type Query { hello: String }
`;

const resolvers = {
  Query: { hello: () => "Hello, world!" },
};

const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
});
console.log(`Server ready at ${url}`);

Integração Express

Para Express, use expressMiddleware de @apollo/server/express4. Inicie o servidor antes de montar o middleware. A função de context recebe o req/res do Express, permitindo ler headers, sessões ou anexar auth. Isso compõe o GraphQL numa app Express existente.

graphql
import { ApolloServer } from "@apollo/server";
import { expressMiddleware } from "@apollo/server/express4";
import express from "express";
import cors from "cors";
import bodyParser from "body-parser";

const app = express();
const server = new ApolloServer({ typeDefs, resolvers });
await server.start();

app.use("/graphql", cors(), bodyParser.json(),
  expressMiddleware(server, {
    context: async ({ req }) => ({ user: getUser(req) }),
  })
);
app.listen(4000);

Construção do schema

makeExecutableSchema (de @graphql-tools/schema) constrói um schema a partir de typeDefs e resolvers, retornando um objeto GraphQLSchema que você passa ao ApolloServer. Essa indireção habilita schema transforms, mesclagem de múltiplos módulos e aplicação de diretivas personalizadas — útil em bases de código maiores.

graphql
import { makeExecutableSchema } from "@graphql-tools/schema";

const schema = makeExecutableSchema({
  typeDefs,
  resolvers,
});

const server = new ApolloServer({ schema });

// makeExecutableSchema lets you apply schema transforms,
// directive visitors, and merge modules before serving.

Função de context

A função de context roda uma vez por requisição, e seu valor de retorno é compartilhado pelos resolvers. Leia os headers de auth e anexe o usuário autenticado, clientes de banco de dados e DataLoaders novos aqui. Lance dentro do context para rejeitar uma requisição antes de qualquer resolver rodar (por exemplo, auth inválida).

graphql
const server = new ApolloServer({ typeDefs, resolvers });

const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => {
    const token = req.headers.authorization || "";
    const user = await verifyToken(token);
    return { user, db, loaders: makeLoaders() };
  },
  listen: { port: 4000 },
});

Apollo Studio / Sandbox

Apollo Sandbox (no navegador, na URL do seu servidor) permite explorar o schema e rodar operações durante o desenvolvimento. Apollo Studio é a contraparte na nuvem para histórico de schema, métricas e tracing. Desabilite a introspecção em produção se quiser esconder seu schema de curiosos.

graphql
# Apollo Sandbox is a dev IDE in the browser
# Visit the server URL in a browser to open it.

const server = new ApolloServer({
  typeDefs,
  resolvers,
  // Apollo Studio reports go through this key (optional)
  // apollo: { graphRef: "my-graph@current" },
});

# For introspection in production, enable it explicitly:
# new ApolloServer({ introspection: true });

Ciclo de vida da requisição

Apollo Server roda um ciclo de vida por requisição: construir o context, interpretar a query, validar contra o schema, executar resolvers, e então formatar a resposta. formatError personaliza a forma dos erros; plugins engancham fases como didResolveOperation, willSendResponse — ótimo para logging, caching e métricas.

graphql
# Order: HTTP request -> context -> parse -> validate ->
#        execute (resolvers) -> format response -> HTTP response

const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (formatted, error) => ({
    message: error.message,
    code: formatted.extensions?.code,
  }),
  plugins: [loggingPlugin, cachePlugin],
});

# plugins hook into every lifecycle phase.

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.