Um guia para iniciantes do GraphQL

Leonardo Maldonado Blocked Unblock Seguir Seguindo 4 de janeiro

Um dos termos mais discutidos hoje é a API. Muitas pessoas não sabem exatamente o que é uma API. Basicamente, API significa Application Programming Interface. É, como o nome diz, uma interface com a qual as pessoas – desenvolvedores, usuários, consumidores – podem interagir com os dados.

Você pode pensar em uma API como um bartender. Você pede ao barman uma bebida, e eles lhe dão o que você queria. Simples. Então, por que isso é um problema?

Desde o início da Web moderna, a criação de APIs não foi tão difícil quanto parece. Mas aprender e entender APIs foi. Os desenvolvedores formam a maioria das pessoas que usarão sua API para criar algo ou apenas consumir dados. Portanto, sua API deve ser a mais limpa e intuitiva possível. Uma API bem projetada é muito fácil de usar e aprender. Também é intuitivo, um bom ponto para se lembrar de quando você está começando a projetar sua API.

Estamos usando o REST para criar APIs por um longo tempo. Junto com isso vem alguns problemas. Ao criar uma API usando o design REST, você terá alguns problemas como:

1) você terá muitos endpoints

2) será muito mais difícil para os desenvolvedores aprenderem e entenderem sua API

3) há sobre-e sub-buscando de informação

Para resolver esses problemas, o Facebook criou o GraphQL. Hoje, acho que o GraphQL é a melhor maneira de criar APIs. Este artigo lhe dirá por que você deve começar a aprender hoje.

Neste artigo, você aprenderá como o GraphQL funciona. Eu vou mostrar como criar uma API poderosa, eficiente e bem desenhada usando o GraphQL.

Você provavelmente já ouviu falar sobre o GraphQL, já que muitas pessoas e empresas o estão usando. Como o GraphQL é open-source, sua comunidade cresceu enormemente.

Agora, é hora de você começar a aprender na prática como o GraphQL funciona e tudo sobre sua mágica.

O que é o GraphQL?

GraphQL é uma linguagem de consulta de código aberto desenvolvida pelo Facebook. Ele nos fornece uma maneira mais eficiente de projetar, criar e consumir nossas APIs. Basicamente, é o substituto do REST.

O GraphQL possui muitos recursos, como:

  1. Você escreve os dados desejados e obtém exatamente os dados desejados. Não mais busca de informações como estamos acostumados com o REST.
  2. Isso nos dá um endpoint único , não mais versão 2 ou versão 3 para a mesma API.
  3. O GraphQL é fortemente tipado , e com isso você pode validar uma consulta dentro do sistema do tipo GraphQL antes da execução. Nos ajuda a criar APIs mais poderosas.

Esta é uma introdução básica ao GraphQL – por que é tão poderosa e por que está ganhando muita popularidade hoje em dia. Se você quiser saber mais sobre isso, eu recomendo que você vá ao site GraphQL e confira.

Começando

O objetivo principal deste artigo não é aprender como configurar um servidor GraphQL, então não estamos nos aprofundando nisso por enquanto. O objetivo é aprender como o GraphQL funciona na prática, então vamos usar um servidor GraphQL de configuração zero chamado ?? Graphpack .

Para começar nosso projeto, vamos criar uma nova pasta e você pode nomear como quiser. Vou nomeá-lo graphql-server :

Abra seu terminal e digite:

 mkdir graphql-server 

Agora, você deve ter o npm ou o fio instalado em sua máquina. Se você não sabe o que são, o npm e o fio são gerenciadores de pacotes para a linguagem de programação JavaScript. Para o Node.js, o gerenciador de pacotes padrão é npm .

Dentro da pasta criada, digite o seguinte comando:

 npm init -y 

Ou se você usar fio:

 yarn init 

O npm criará um arquivo package.json para você e todas as dependências que você instalou e seus comandos estarão lá.

Então, agora, vamos instalar a única dependência que vamos usar.

?? O Graphpack permite criar um servidor GraphQL com configuração zero . Já que estamos começando com o GraphQL, isso nos ajudará muito a continuar e aprender mais sem se preocupar com a configuração do servidor.

No seu terminal, dentro da sua pasta raiz, instale-o assim:

 npm install --save-dev graphpack 

Ou, se você usar fio, você deve ir assim:

 yarn add --dev graphpack 

Depois que o Graphpack estiver instalado, vá para nossos scripts no arquivo package.json e coloque o seguinte código lá:

Nós vamos criar uma pasta chamada src , e esta será a única pasta em todo o nosso servidor.

Crie uma pasta chamada src , depois disso, dentro da nossa pasta, vamos criar apenas três arquivos.

Dentro de nossa pasta src crie um arquivo chamado schema.graphql . Dentro deste primeiro arquivo, coloque o seguinte código:

Neste arquivo schema.graphql vai estar todo o nosso esquema GraphQL. Se você não sabe o que é, eu explicarei depois – não se preocupe.

Agora, dentro de nossa pasta src , crie um segundo arquivo. Chame-lhe resolvers.js e, dentro deste segundo arquivo, coloque o seguinte código:

Este arquivo resolvers.js será o modo como fornecemos as instruções para transformar uma operação GraphQL em dados.

E finalmente, dentro da sua pasta src , crie um terceiro arquivo. Chame isso de db.js e, dentro deste terceiro arquivo, coloque o seguinte código:

Neste tutorial não estamos usando um banco de dados do mundo real. Portanto, este arquivo db.js irá simular um banco de dados, apenas para fins de aprendizado.

Agora nossa pasta src deve ficar assim:

 src 
|--db.js
|--resolvers.js
|--schema.graphql

Agora, se você executar o comando npm run dev ou, se você estiver usando o yarn, yarn dev , deverá ver esta saída no seu terminal:

Agora você pode ir para localhost:4000 . Isso significa que estamos prontos para começar a escrever nossas primeiras consultas, mutações e assinaturas no GraphQL.

Você vê o GraphQL Playground, um poderoso IDE GraphQL para melhores fluxos de trabalho de desenvolvimento. Se você quiser saber mais sobre o GraphQL Playground, clique aqui .

Esquema

O GraphQL tem seu próprio tipo de linguagem usado para escrever esquemas. Essa é uma sintaxe de esquema legível por humanos, chamada Linguagem de definição de esquema (SDL). O SDL será o mesmo, não importa qual tecnologia você esteja usando – você pode usá-lo com qualquer linguagem ou estrutura que desejar.

Essa linguagem de esquema é muito útil porque é simples entender quais tipos sua API terá. Você pode entender isso apenas olhando corretamente.

Tipos

Os tipos são um dos recursos mais importantes do GraphQL. Tipos são objetos personalizados que representam a aparência da sua API. Por exemplo, se você está criando um aplicativo de mídia social, sua API deve ter tipos como Posts , Users , Likes , Groups .

Os tipos possuem campos e esses campos retornam um tipo específico de dados. Por exemplo, vamos criar um tipo de usuário, devemos ter alguns campos de name , email e age . Os campos de tipo podem ser qualquer coisa e sempre retornam um tipo de dado como Int, Float, String, Boolean, ID, uma lista de tipos de objetos ou tipos de objetos personalizados .

Então, agora para escrever nosso primeiro Type, vá para o seu arquivo schema.graphql e substitua o tipo Query que já está lá com o seguinte:

Cada User terá um ID , por isso, fornecemos um tipo de ID . User também terá um name e um e- email , por isso, atribuímos a ele um tipo String e uma age , age quais Int um tipo Int . Muito simples, certo?

Mas e aqueles ! no final de cada linha? O ponto de exclamação significa que os campos não são anuláveis , o que significa que cada campo deve retornar alguns dados em cada consulta. O único campo anulável que teremos em nosso tipo de User será a age .

No GraphQL, você lidará com três conceitos principais:

  1. consultas – a maneira como você obterá dados do servidor.
  2. mutações – a maneira como você modificará os dados no servidor e recuperará os dados atualizados (criar, atualizar, excluir).
  3. assinaturas – a maneira como você vai manter uma conexão em tempo real com o servidor.

Eu vou explicar todos eles para você. Vamos começar com as consultas.

Consultas

Para explicar isso de uma maneira simples, as consultas no GraphQL são como você obterá dados. Uma das coisas mais bonitas sobre as consultas no GraphQL é que você irá obter os dados exatos que deseja. Nem mais nem menos. Isso tem um enorme impacto positivo em nossa API – não mais informações de busca ou subtransferência, como as APIs REST.

Vamos criar nosso primeiro tipo de consulta no GraphQL. Todas as nossas consultas acabarão dentro desse tipo. Então, para começar, vamos ao nosso schema.graphql e escrevemos um novo tipo chamado Query :

É muito simples: os users consulta irá retornar para nós uma matriz de um ou mais Users . Não retornará null, porque colocamos no ! , o que significa que é uma consulta não anulável. Deve sempre devolver alguma coisa.

Mas também podemos retornar um usuário específico. Para isso, vamos criar uma nova consulta chamada user . Dentro do nosso tipo de Query , coloque o seguinte código:

Agora, nosso tipo de Query deve ficar assim:

Como você pode ver, com consultas no GraphQL também podemos passar argumentos. Nesse caso, para consultar um user específico, passaremos seu ID .

Mas você pode estar se perguntando: como o GraphQL sabe onde obter os dados? É por isso que devemos ter um arquivo resolvers.js . Esse arquivo informa ao GraphQL como e onde ele vai buscar os dados.

Primeiro, vá para o nosso arquivo resolvers.js e importe o db.js que acabamos de criar alguns momentos atrás. Seu arquivo resolvers.js deve ficar assim:

Agora, vamos criar nossa primeira consulta. Vá para o seu arquivo resolvers.js e substitua a função hello . Agora o seu tipo de consulta deve ficar assim:

Agora, para explicar como isso vai funcionar:

Cada resolvedor de consulta tem quatro argumentos. Na função de user , passaremos id como um argumento e, em seguida, retornaremos o user específico que corresponde ao id passado. Bem simples.

Na função de users , vamos apenas retornar a matriz de users que já existe. Ele sempre retornará para todos os nossos usuários.

Agora, vamos testar se nossas consultas estão funcionando bem. Vá para localhost:4000 e coloque o seguinte código:

Ele deve retornar a você todos os nossos usuários.

Ou, se você quiser retornar um usuário específico:

Agora, vamos começar a aprender sobre mutações , um dos recursos mais importantes do GraphQL.

Mutações

No GraphQL, as mutações são a maneira de modificar os dados no servidor e recuperar os dados atualizados. Você pode pensar como o CUD (Create, Update, Delete) do REST.

Nós vamos criar nossa primeira mutação de tipo no GraphQL, e todas as nossas mutações vão acabar dentro deste tipo. Então, para começar, vá para o nosso schema.graphql e escreva um novo tipo chamado mutation :

Como você pode ver, vamos ter três mutações:

createUser : devemos passar um ID , name , email e age . Deve nos devolver um novo usuário.

updateUser : devemos passar um ID e um novo name , email ou age . Deve nos devolver um novo usuário.

deleteUser : devemos passar um ID , name , email e age . Deve nos devolver um novo usuário.

Agora, vá para o nosso arquivo resolvers.js e abaixo do objeto Query , crie um novo objeto de mutation como este:

Agora, nosso arquivo resolvers.js deve ficar assim:

Agora, vamos testar se nossas mutações estão funcionando bem. Vá para localhost:4000 e coloque o seguinte código:

Deve devolver um novo usuário para você. Se você quiser tentar fazer novas mutações, recomendo que você tente por si mesmo! Tente excluir esse mesmo usuário que você criou para ver se está funcionando bem.

Finalmente, vamos começar a aprender sobre assinaturas e por que elas são tão poderosas.

Assinaturas

Como eu disse antes, as assinaturas são a maneira de manter uma conexão em tempo real com um servidor. Isso significa que sempre que um evento ocorrer no servidor e sempre que esse evento for chamado, o servidor enviará os dados correspondentes ao cliente.

Ao trabalhar com assinaturas, você pode manter seu aplicativo atualizado para as últimas alterações entre diferentes usuários.

Uma assinatura básica é assim:

Você dirá que é muito semelhante a uma consulta e sim é. Mas funciona de maneira diferente.

Quando algo é atualizado no servidor, o servidor executará a consulta GraphQL especificada na assinatura e enviará um resultado recém-atualizado ao cliente.

Não vamos trabalhar com assinaturas neste artigo específico, mas se você quiser ler mais sobre elas, clique aqui .

Conclusão

Como você viu, o GraphQL é uma nova tecnologia que é realmente poderosa. Isso nos dá poder real para criar APIs melhores e bem projetadas. É por isso que recomendo que você comece a aprender agora. Para mim, acabará substituindo o REST.

Obrigado por ler o artigo, por favor, dê um comentário abaixo!

? Siga-me no Twitter!
? Siga-me no GitHub!

Estou à procura de uma oportunidade remota, por isso, se tiver algum eu gostaria de ouvir sobre isso, então por favor contacte-me no meu Twitter !