Biblioteca GraphQL JavaScript (Node.js) — Guia Completo

Biblioteca GraphQL JavaScript (Node.js): Guia Completo

GraphQL é uma linguagem de consulta e ambiente de execução para APIs, desenvolvida pelo Facebook. No ecossistema Node.js, a principal biblioteca para trabalhar com GraphQL é o pacote graphql. Ele fornece todas as ferramentas necessárias para criar, validar e executar consultas GraphQL. Esta biblioteca é a base para frameworks populares como Apollo Server, Express-GraphQL e outros.

O que é GraphQL e por que usá-lo?

Ao contrário das APIs REST, onde cada endpoint retorna uma estrutura de dados fixa, o GraphQL permite que o cliente solicite apenas os campos de que precisa. Isso resolve o problema de over-fetching (obter dados desnecessários) e under-fetching (falta de dados). Principais vantagens:

• Flexibilidade de consultas: o cliente decide quais dados obter.
• Ponto de entrada único: todas as consultas vão para um único endpoint (ex.: /graphql).
• Tipagem forte: o esquema GraphQL define os tipos de dados e suas relações.
• Introspecção: é possível gerar automaticamente documentação e ferramentas de teste (GraphiQL).

Instalação da biblioteca GraphQL para Node.js

Para começar, instale o pacote via npm ou yarn:

npm install graphql

Você também precisará de um servidor HTTP, como express, e middleware express-graphql (ou Apollo Server). Mas a própria biblioteca graphql é o núcleo.

Criando o primeiro esquema e resolver

O esquema é a descrição dos tipos de dados e operações disponíveis (consultas, mutações). Resolvers são funções que executam a lógica real de obtenção de dados.

Exemplo de um esquema simples com um tipo User e uma consulta user:

const { graphql, buildSchema } = require('graphql');

// Definindo o esquemaconst schema = buildSchema(`  type User {    id: ID!    name: String    email: String  }

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

// Dados (em um projeto real, seria um banco de dados)const users = [  { id: '1', name: 'João', email: 'joao@example.com' },  { id: '2', name: 'Maria', email: 'maria@example.com' }];

// Resolversconst root = {  user: ({ id }) => users.find(user => user.id === id)};

// Executando a consultagraphql({  schema,  source: '{ user(id: "1") { name email } }',  rootValue: root}).then(response => {  console.log(JSON.stringify(response));  // {"data":{"user":{"name":"João","email":"joao@example.com"}}}});

Tipos de dados no GraphQL

A biblioteca graphql suporta todos os tipos escalares padrão:

• String — texto;
• Int — número inteiro;
• Float — número de ponto flutuante;
• Boolean — valor lógico;
• ID — identificador único (serializado como string).

Também é possível criar tipos de objeto personalizados, enumerações (enum), listas ([Type]) e campos não nulos (Type!).

Mutações e assinaturas

Mutações são usadas para modificar dados (análogo a POST/PUT/DELETE no REST). Assinaturas permitem receber atualizações em tempo real via WebSocket.

Exemplo de mutação para adicionar um usuário:

const schema = buildSchema(`  type Mutation {    addUser(name: String!, email: String!): User  }`);

const root = {  addUser: ({ name, email }) => {    const newUser = { id: String(users.length + 1), name, email };    users.push(newUser);    return newUser;  }};

// Executando a mutaçãographql({  schema,  source: 'mutation { addUser(name: "Pedro", email: "pedro@example.com") { id name } }',  rootValue: root}).then(console.