Introdução ao GraphQL com Apollo Server: Guia Completo para Iniciar com Exemplos

Introdução ao GraphQL com Apollo Server: Guia Completo para Iniciar com Exemplos

“`html




Introdução ao GraphQL com Apollo Server

GraphQL + Apollo Server

Introdução ao GraphQL com Apollo Server

Se você quer uma API com contrato tipado, consultas flexíveis e implementação organizada, GraphQL com Apollo Server é um ótimo ponto de partida.
Neste post, eu te guio pelos conceitos essenciais e por um exemplo funcional.

1

O que é GraphQL (e por que ele muda a forma de consumir APIs)

GraphQL é uma linguagem de consulta para APIs. Em vez de existirem múltiplos endpoints “fixos” (por recurso e variações),
você descreve exatamente quais campos quer buscar. Isso reduz overfetch (buscar dados a mais) e underfetch (faltar dados).

  • Schema como contrato: GraphQL começa com um schema que define tipos, campos e relações.
  • Resolução por campo: o servidor resolve a consulta de acordo com o que foi pedido.
  • Query determinística: a resposta segue a estrutura pedida no request.
↳

Em prática: no REST, você tenta “encaixar” recursos em endpoints; no GraphQL, você encaixa os dados no formato que a UI realmente precisa.

2

Fundamentos do schema: tipos, campos e resolvers

O schema é o coração do GraphQL. Ele define o que existe no seu domínio e como isso pode ser consultado.
Para cada campo do schema, você implementa um resolver (função que retorna o valor).

Principais peças

  • Type: estrutura de dados (ex.: User).
  • Query/Mutation: entrada principal para leitura e escrita.
  • Argumentos: filtros e parâmetros (ex.: user(id: ID!)).
  • Scalar: tipos básicos (ex.: String, Int, ID).
  • Non-null (!): garante que o valor sempre existirá.

Como pensar em resolvers

  • Resolver somente o que foi pedido.
  • Evitar acoplamento: resolvers devem orquestrar chamadas para sua camada de dados.
  • Padronizar tratamento de erro e validação.
  • Considerar performance: caching e carregamento eficiente.

3

Subindo o Apollo Server: pipeline básico e execução da consulta

O Apollo Server é um servidor GraphQL para Node.js. Ele conecta:
schema, resolvers e um endpoint HTTP (geralmente /graphql).

  • Entrada: o cliente envia uma query (e variáveis) via HTTP.
  • o Apollo interpreta a query, valida contra o schema e chama os resolvers dos campos.
  • retorna data (e errors quando necessário).
⚙

Dica: trate autenticação/authorization no nível de contexto do request, para os resolvers consumirem permissões com consistência.

4

Exemplo prático: API de usuários com Apollo Server

Abaixo está um exemplo mínimo, mas realista: definimos o schema com type e Query,
implementamos resolvers e expomos o endpoint GraphQL.

server.ts (Apollo Server com schema + resolvers)

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

const typeDefs = gql`
  type User {
    id: ID!
    name: String!
    email: String!
  }

  type Query {
    user(id: ID!): User
    users: [User!]!
  }
`;

const usersData = [
  { id: "1", name: "Marina Alves", email: "marina@exemplo.com" },
  { id: "2", name: "Rafael Souza", email: "rafael@exemplo.com" }
];

const resolvers = {
  Query: {
    user: (_parent: unknown, args: { id: string }) => {
      return usersData.find(u => u.id === args.id) ?? null;
    },
    users: () => {
      return usersData;
    }
  }
};

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

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 }
});

console.log(`GraphQL pronto em ${url}`);

Consultando com GraphQL (exemplo de query):

Query para buscar um usuário

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

✓

Repare como o schema define claramente o que pode ser retornado. Isso facilita o trabalho do front-end e mantém o contrato estável.



“`