GraphQL — o que é, linguagem de consulta e aplicação em projetos mobile

O que é GraphQL?

GraphQL — é uma especificação e ambiente de execução para APIs que dá ao cliente controle total sobre os dados que recebe. Desenvolvida por engenheiros do Facebook para resolver os problemas do aplicativo móvel News Feed, a especificação foi publicada como um padrão aberto em 2015. Desde 2018, o GraphQL é gerenciado pela GraphQL Foundation com o apoio da Linux Foundation e empresas como Apollo, AWS, GitHub, SAP e outras.

Diferente do REST, onde cada endpoint retorna uma estrutura de dados fixa, o GraphQL usa um único endpoint que aceita uma string de consulta. O cliente descreve na consulta quais campos precisa, e o servidor retorna exatamente esses. Por exemplo, a consulta { user(id: "1") { name email } } retornará apenas o nome e email do usuário, sem campos extras como address, phone ou createdAt que seriam necessários no REST.

O GraphQL não está vinculado a nenhum banco de dados ou linguagem específica. A especificação define apenas o formato de consultas e respostas. Existem implementações de servidor em Node.js (graphql-js, Apollo Server), Kotlin (graphql-kotlin, Netflix DGS Framework), Python (Graphene, Strawberry), Ruby (graphql-ruby) e outras linguagens. Bibliotecas cliente estão disponíveis para todas as principais plataformas, incluindo Apollo Client para iOS, Android e web.

Como o GraphQL funciona

A arquitetura do GraphQL consiste em três componentes principais: Esquema (Schema), Resolvedores (Resolvers) e o Mecanismo GraphQL (GraphQL Engine). O esquema define quais tipos de dados estão disponíveis, quais consultas podem ser executadas e quais argumentos aceitam. Os resolvedores são funções do lado do servidor que retornam dados para cada campo do esquema. O mecanismo recebe a consulta de entrada, valida-a contra o esquema, chama os resolvedores apropriados e monta a resposta.

O processo de processamento da consulta é o seguinte:

• O cliente envia uma requisição POST para /graphql com um corpo JSON { "query": "..." }
• O servidor analisa a consulta, constrói uma AST (Árvore Sintática Abstrata) e valida contra o esquema
• O mecanismo percorre a AST, chamando resolvedores para cada campo, coletando dados
• A resposta é retornada em formato JSON, correspondendo estritamente à estrutura da consulta

A principal vantagem da arquitetura GraphQL é a resolução no nível do campo. No REST, o desenvolvedor obtém todos os campos de um recurso (possivelmente com extras) ou recorre a extensões como ?fields=name,email. No GraphQL, essa filtragem está incorporada na linguagem: cada consulta especifica explicitamente quais campos são necessários, e o servidor retorna exatamente esses. Isso é especialmente importante para aplicativos móveis, onde a quantidade de dados transferidos afeta diretamente a velocidade de carregamento e o consumo de dados.

Query, Mutation e Subscription

O GraphQL define três tipos de operações, cada um correspondendo a um cenário de interação específico. Query — para leitura de dados, análogo ao GET no REST. Mutation — para modificar dados (criar, atualizar, excluir), análogo ao POST/PUT/DELETE. Subscription — para atualizações em tempo real via WebSocket, que não tem análogo direto no REST clássico (requer soluções adicionais como WebSocket ou Server-Sent Events).

A sintaxe básica das consultas é intuitiva:

// Consulta simples com argumento
query {
    user(id: "42") {
        name
        email
        avatarUrl
    }
}

// Mutation retornando dados modificados
mutation {
    updateProfile(name: "Ivan") {
        id
        name
        updatedAt
    }
}

// Subscription — ouve atualizações em tempo real
subscription {
    newMessage(chatId: "chat_1") {
        id
        text
        sender { name }
    }
}

Query é executada em paralelo — todos os campos no mesmo nível são carregados simultaneamente. Isso permite carregar dados relacionados (usuário e suas postagens) em uma única requisição sem múltiplas viagens de ida e volta. Mutation é executada sequencialmente — mutações em uma requisição são executadas uma após a outra na ordem de declaração. Subscription estabelece uma conexão persistente via WebSocket, pela qual o servidor envia dados quando um evento ocorre.

As operações podem aceitar variáveis para separar dados da consulta, diretivas (@include, @skip) para inclusão condicional de campos e fragmentos para reutilizar conjuntos de campos. Esses recursos tornam as consultas GraphQL flexíveis e reutilizáveis, o que é especialmente importante em grandes projetos com múltiplas telas e componentes.

Esquema e sistema de tipos do GraphQL

No centro do GraphQL está um sistema de tipos que descreve todos os dados e operações possíveis da API. O esquema é uma descrição dos tipos que o servidor pode retornar e as consultas que aceita. O esquema é escrito em Schema Definition Language (SDL) e serve como um contrato entre cliente e servidor. O cliente pode obter o esquema através de introspecção — uma consulta especial __schema que retorna uma descrição completa da API.

Exemplo de esquema para um blog:

// SDL — Schema Definition Language
type User {
    id: ID!
    name: String!
    email: String
    posts: [Post!]!
}

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

type Query {
    user(id: ID!): User
    posts(page: Int): [Post!]!
}

O ponto de exclamação (!) indica um campo não nulo — ele estará garantidamente presente na resposta. Colchetes [ ] denotam uma lista. O GraphQL suporta tipos escalares (Int, Float, String, Boolean, ID), tipos de objeto, enum, union, interface e tipos de entrada (para argumentos de mutações). A tipagem estrita autodocumenta a API e permite que ferramentas cliente gerem código: tipos TypeScript, classes de dados Kotlin, estruturas Swift.

Introspecção é uma característica única do GraphQL ausente no REST. O cliente pode enviar uma consulta ao esquema e obter uma descrição completa de todos os tipos, campos, argumentos e diretivas. Isso é a base de ferramentas como GraphiQL e Apollo Studio, que geram automaticamente documentação e autocompletar para desenvolvedores. A introspecção também permite escrever testes automatizados que verificam a conformidade do esquema com a estrutura esperada.

Comparação do GraphQL com REST

A escolha entre GraphQL e REST é uma das principais decisões arquiteturais ao projetar uma API. Ambas as abordagens têm pontos fortes e fracos, e a escolha depende dos requisitos específicos do projeto. O REST vence em simplicidade e universalidade, o GraphQL em flexibilidade e eficiência de consultas. Vamos à tabela comparativa.

A principal desvantagem do GraphQL é a complexidade do cache. No REST, o cache HTTP funciona no nível da URL: uma requisição para /api/users/42 sempre retorna a mesma estrutura, e a resposta pode ser armazenada em cache por URL. No GraphQL, todas as requisições vão para um único endpoint, e a estrutura da resposta depende do corpo da requisição. Para resolver isso, o Apollo Client usa um cache normalizado no lado do cliente, que divide as respostas em entidades individuais por id e as atualiza automaticamente ao receber novos dados.

Outro aspecto importante é o problema N+1. Ao solicitar dados aninhados (por exemplo, postagens do usuário e comentários para cada postagem), o GraphQL pode executar uma consulta SQL separada para cada item da lista. Isso é resolvido com DataLoader — uma utilidade para agrupar e armazenar em cache consultas de banco de dados, que agrupa requisições individuais em um único lote. No REST, esse problema é menos pronunciado, pois o desenvolvedor controla a estrutura da resposta no lado do servidor.

Exemplos de consultas GraphQL

Vamos ver exemplos práticos do uso de GraphQL em um aplicativo móvel Kotlin com Apollo Client. Os exemplos demonstram cenários típicos: carregamento de dados para uma tela de perfil (query), criação de uma nova postagem (mutation) e assinatura de novos comentários (subscription). Cada exemplo inclui tanto a consulta GraphQL quanto o código do lado do cliente.

Query: Carregamento de perfil com postagens

Uma única consulta GraphQL carrega o usuário, suas últimas postagens e o número total de seguidores. No REST, isso exigiria pelo menos 2-3 requisições: /users/42, /users/42/posts, /users/42/stats. O GraphQL as combina em uma única viagem de ida e volta, reduzindo o tempo de carregamento da tela em conexões lentas.

// Consulta GraphQL (no arquivo .graphql)
query ProfileScreen($userId: ID!) {
    user(id: $userId) {
        name
        bio
        avatarUrl
        posts(limit: 10) {
            id
            title
            createdAt
        }
        followersCount
        followingCount
    }
}

// Chamada no cliente (Apollo Client + Kotlin)
val response = apolloClient
    .query(ProfileScreenQuery(userId = "42"))
    .execute()
binding.nameText.text = response.data?.user?.name

Mutation: Criando uma nova postagem

A mutação não apenas cria um recurso, mas também retorna seus dados atuais para atualizar a interface do usuário. O campo __typename é usado pelo Apollo Client para normalização do cache — o cliente atualizará automaticamente o registro Post no cache ao receber uma resposta bem-sucedida da mutação.

// Mutation GraphQL
mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) {
        id
        title
        createdAt
        author {
            id
            name
        }
    }
}

// Chamada de mutation com tipo input
val input = CreatePostInput(
    title = "Nova postagem sobre GraphQL",
    content = "GraphQL simplifica o trabalho com API..."
)
val result = apolloClient
    .mutation(CreatePostMutation(input))
    .execute()

Uma vantagem importante do GraphQL sobre o REST no contexto do desenvolvimento mobile é a geração automática de código. O Apollo Client para Kotlin (Apollo GraphQL) gera classes seguras quanto ao tipo a partir de arquivos .graphql em tempo de compilação. Se o servidor alterar o esquema, o projeto não será compilado até que as consultas sejam atualizadas. Isso evita erros de tempo de execução típicos do REST, onde mudanças na estrutura da resposta podem passar despercebidas durante o desenvolvimento.

Ecossistema: Apollo, Relay e ferramentas

O ecossistema GraphQL inclui várias bibliotecas e ferramentas importantes que simplificam o desenvolvimento e a operação. Apollo Client é a biblioteca cliente mais popular, com suporte a React, iOS, Android e Kotlin Multiplatform. Relay do Facebook é uma alternativa para aplicativos React com uma abordagem única para gerenciamento de dados e cache. A escolha entre Apollo e Relay depende da plataforma e dos requisitos de desempenho.

No lado do servidor, os líderes são Apollo Server (Node.js), Netflix DGS Framework (Kotlin/Java) e graphql-ruby. Para desenvolvimento de esquemas e teste de consultas, GraphiQL é usado — um IDE interativo incorporado ao navegador. O Apollo Studio fornece métricas de desempenho, rastreamento de consultas e gerenciamento de esquemas para ambientes de produção. Menção à parte merece o GraphQL Code Generator — uma ferramenta que gera tipos TypeScript, Kotlin, Swift e Dart a partir de um esquema SDL.

Para desenvolvimento mobile, Apollo Kotlin (Apollo GraphQL) é de particular interesse — uma biblioteca inteiramente escrita em Kotlin com suporte a corrotinas, Flow e Multiplatform. Permite usar consultas GraphQL unificadas para Android e iOS em projetos Kotlin Multiplatform. O Apollo Kotlin normaliza o cache, suporta erros no nível do campo (erros parciais) e gera automaticamente modelos de dados a partir de arquivos .graphql. Isso torna o GraphQL a escolha preferida para grandes projetos mobile onde velocidade de desenvolvimento e segurança de tipos são importantes.