Fundamentos de GraphQL para desenvolvedores React

O REST expõe pontos de acesso de formato fixo: GET /users/:id retorna todo o objeto do usuário, independentemente do que o cliente precisa. O GraphQL permite que os clientes especifiquem exatamente quais campos desejam, eliminando a busca excessiva (dados demais) e a busca insuficiente (dados de menos, exigindo várias solicitações).

Uma única consulta GraphQL pode recuperar um usuário, suas publicações e o autor de cada publicação em uma única viagem de ida e volta.

Toda API GraphQL é definida por um esquema escrito na Linguagem de Definição de Esquema (SDL). O esquema declara tipos, seus campos e os tipos raiz Query, Mutation e Subscription, sobre os quais os clientes podem operar.

O esquema é o contrato entre o cliente e o servidor. As equipes do cliente e do servidor podem trabalhar em paralelo depois que o esquema for acordado.

Uma consulta GraphQL seleciona campos: { user(id: "1") { name email posts { title } } }. Os campos aninhados percorrem relações em uma única solicitação. Os apelidos renomeiam campos: { me: user(id: "1") { name } }. Os fragmentos reutilizam seleções de campos em várias consultas.

As variáveis tornam as consultas reutilizáveis: query GetUser($id: ID!) { user(id: $id) { name } } com as variáveis: { id: "1" }.

Cada campo do esquema GraphQL tem uma função de resolução no servidor. Quando um cliente consulta user.name, a função de resolução de user busca o objeto do usuário e a função de resolução de name (ou a função de resolução padrão) retorna o campo name.

Essa resolução em nível de campo é o que permite ao GraphQL buscar precisamente apenas os dados solicitados.

Se você consultar uma lista de 100 publicações e cada publicação incluir seu autor, a implementação ingênua disparará 100 consultas separadas ao banco de dados para buscar os autores. Esse problema N+1 torna as APIs GraphQL lentas sem otimização.

O DataLoader resolve o problema N+1 agrupando todas as buscas de autores em uma única consulta ao banco de dados, usando um cache por solicitação e uma função de agrupamento.

O Apollo Studio e o GraphQL Playground são interfaces executadas no navegador para explorar uma API GraphQL de forma interativa. Eles completam automaticamente os campos a partir do esquema, exibem os resultados das consultas e mostram a documentação dos tipos diretamente na interface.

Usar essa ferramenta é a maneira mais rápida de entender uma API GraphQL desconhecida antes de escrever o código do cliente.

As APIs GraphQL expõem o próprio esquema por meio de uma consulta de introspecção: { __schema { types { name } } }. Os clientes podem consultar o próprio esquema para descobrir os tipos, campos e argumentos disponíveis.

Ferramentas de geração de código, como graphql-codegen, usam a introspecção para gerar automaticamente tipos TypeScript correspondentes ao esquema da API.

As mutações do GraphQL modificam dados: mutation CreatePost($input: PostInput!) { createPost(input: $input) { id title } }. As assinaturas estabelecem uma conexão persistente (geralmente WebSocket) e enviam atualizações: subscription { postAdded { id title } }.

Todos os três tipos raiz (Query, Mutation, Subscription) usam a mesma sintaxe de seleção de campos.

GraphQL se destaca em aplicações com requisitos de dados complexos e aninhados, vários tipos de clientes (móvel, web, TV) que precisam de subconjuntos de campos diferentes ou APIs que evoluem rapidamente, nas quais a descontinuação de campos é preferível ao versionamento de pontos de extremidade.

REST é mais simples para APIs CRUD com formatos de recursos previsíveis e planos, além de excelentes características de armazenamento em cache HTTP por meio de ETags e cabeçalhos de cache.

Apollo Client é o cliente GraphQL com mais recursos: cache normalizado, gerenciamento de estado local, assinaturas e elos para tratamento de erros. URQL é mais leve, com um cache de documentos e uma API mais simples. React Query com graphql-request é a abordagem mais simples para consultas e mutações básicas, sem recursos avançados de cache.

Escolha com base nos seus requisitos de cache: use um cache normalizado para entidades compartilhadas entre consultas (Apollo) e um cache de documentos mais simples para consultas independentes (URQL ou React Query).

Uma SDL simples: type User { id: ID! name: String! posts: [Post!]! } type Post { id: ID! title: String! author: User! } type Query { user(id: ID!): User users: [User!]! }. Os pontos de exclamação indicam campos que não aceitam valores nulos.

Esse esquema informa exatamente ao cliente quais campos existem em cada tipo e quais consultas estão disponíveis, permitindo a geração de código com tipos seguros.

O que significa "buscar dados em excesso" no contexto de REST versus GraphQL?

GraphQL permite que os clientes solicitem exatamente os campos de que precisam (sem buscar dados em excesso ou insuficientes) usando uma linguagem de consulta definida pelo esquema. Os resolvers respondem a cada campo; DataLoader resolve o problema N+1. A introspecção permite gerar código para tipos TypeScript. Apollo Client, URQL e React Query são os principais clientes GraphQL compatíveis com React.

Escolha GraphQL para requisitos de dados complexos, aninhados e destinados a vários clientes; escolha REST para operações CRUD simples com formatos previsíveis.