Forem: Vinicius Reis

Funções Puras e imutabilidade, um pouco sobre código limpo e qualidade

Vinicius Reis — Mon, 16 Sep 2019 20:28:37 +0000

Código limpo (clean code) é um tópico recorrente e importante. Infelizmente não há uma adoção tão grande quanto se imagina ou espera.

Entre as motivações estão a falta de aprofundamento do tópico e suas nuances, bem como uma boa contextualização e a realidade dos projetos ou empresas onde os profissionais de desenvolvimento de software trabalham.
O caos, a cobrança e demanda, muitos líderes ou gerentes não conseguem, ou simplesmente não veem valor nessas práticas, o bom e velho “o importante é funcionar”.

Talvez algumas pessoas fiquem chocadas ou surpresas ao saber que ainda há muitas empresas e profissionais não sigam práticas e conceitos consideradas por muitos básicas.

Este artigo visa ajudar a desmistificar alguns tópicos e técnicas, facilitando a adoção das mesmas.

Clean Code e JavaScript

Clean Code é um assunto extenso, até mesmo controverso em alguns aspectos. Algumas coisas podem ser consideradas subjetivas, debates não são raros.

Infelizmente muitos desses debates são bikeshedding, resultam em nada. Quando isto acontece, quem esta na posição de liderança do time precisa tomar uma postura rígida e clara, algumas vezes unilaterais. Não é algo simples, afinal pode gerar conflitos no time, porém, é algo necessário.

Meu conselho é: seja honesto e claro, a intenção não é impor uma vontade, mas sim encerrar diálogos improdutivos.

Ferramental

Muitas dessas discussões são sobre ponto e vírgula… Tabs ou espaços… CamelCase ou Snake Case… A solução é simples, adotar um estilo pré existente e consolidado e seguir com ele sem nenhuma alteração.

No JavaScript possuímos alguns padrões já bastante populares: Google Style Guide, Airbnb Style Guide e JavaScript Standard Style. Todos possuem suas regras para o ESLint. Escolha um deles e adote para seu time ou projeto, recomendo não fazer modificações nas regras.

Há plataformas que vão além do que o ESLint faz, analisando e classificando seu código. Algumas são gratuitas para projetos open-source.

Técnicas

São várias, este artigo vai se focar em Imutabilidade e Funções Puras. Porém, não podemos deixar de citar algumas como DRY, SOLID, KISS e Object Calisthenics.

Ao se aprofundar nessas técnicas você perceberá a convergência de ideias e fluxos, com o tempo e prática elas se tornaram naturais ao seu estilo de codificação.

Imutabilidade

Imutabilidade talvez seja um dos tópicos mais complexos deste artigo. Não uma complexidade técnica, mas uma complexidade quase filosófica e de alguma falsos positivos.

A primeira coisa que devemos entender, imutabilidade não significa constante.

const a = 73
a = 37

Este é o erro que recebemos ao executar o exemplo anterior, muitos vão assumir que const no JavaScript esta relacionado a constante, porém seu objetivo é impedir a reatribuição de uma variável.

Vamos entender um pouco mais como isso funciona.

Valores e Referências

Em JavaScript temos os seguintes primitivos:

Quando usamos os operadores de comparação == e === internamente e em resumo, estamos comparando referências de memória. JavaScript é uma linguagem 100% orientada a objetos, todos os seus tipos e valores são objetos.

Objetos vão possui um endereço de memória, na prática x == y esta comparando se o endereço de memória que x representa, é o mesmo que y representa. Por isso que {} == {} ou [] == [] não funciona, pois cada {} e [] apontam para locais diferentes da memória.

Sabendo que 2 é do tipo Number e também um objeto, como 2 == 2 funciona? A resposta é simples, os tipos primitivos em JavaScript são constantes e imutáveis.

01. let n = 73
02. n == 73 // true
03. n = 37
04. n == 73 // false

Na linha 01. declaramos n e atribuímos 73 para ele.
Na linha 02. comparamos n == 73, como n aponta para o mesmo endereço de memória que 73 temos true como resultado.
Na linha 03. reatribuímos n a outro valor, agora 37.
Na linha 04. comparamos n == 73, como n aponta para outro endereço e não para 73, temos false como resultado.

Todo primitivo em JavaScript se comporta dessa maneira, outra característica relacionada a este comportamento é a imutabilidade deles, métodos de um primitivo não modificam seu valor… não alteram sua referência na memória, quando necessário geram novas referências, mas nunca modificam a original.

const s1 = 'Codecasts'
const s2 = s1.toUpperCase() // CODECASTS
s1 == s2 // false

Este comportamento é nativo dos primitivos, porém outros tipos como Array e Object não se comportam dessa maneira, [7, 3] == [7, 3] sempre será false, pois cada um aponta para um endereço de memória diferente.

Explaining Value vs. Reference in Javascript

Referências Imutáveis

Quando estamos falando de imutabilidade em JavaScript estamos falando em evitar modificar referências.

Ao usar const em primitivos já estamos garantindo uma boa parcela de imutabilidade, porém o maior desafio é trabalhar com objetos e listas imutáveis.

01. const arr = [7, 3]
02. arr.push(12)           // arr --> [7, 3, 12]
03. arr.unshift(1)         // arr --> [1, 7, 3, 12]
04. const last = arr.pop() // arr --> [1, 7, 3]
05. last == 12 // true

Refs: .push, .unshift e .pop

Na linha 01. declaramos arr, atribuímos nele um array [7, 3]. Nas linhas 02. a 04. manipulamos arr e em seguida é ilustrado seu estado atual.

Inicialmente coisas assim podem parecer inofensivas, mas há um potencial de cenários extremamente difíceis de serem identificados ou rastreados.

O próximo exemplo ilustra como objetos são usados como referência.

const fn = x => x
const obj = {}
obj == fn(obj) // true

A função fn não faz nada além de retornar x seu único argumento. Ao comparar obj == fn(obj) temos true como resultado, pois estamos retornando a mesma instância/referência.

O exemplo abaixo explora brevemente os impactos desse comportamento.

const setPrice = product => {
  product.price = 73
}
const product = { name: 'Instant Kung Foo.' }
setPrice(product)
product.price == 73 // true

A função setPrice recebe product e adiciona ou modifica a propriedade price, isso fica claro quando comparamos product.price == 73. Isso se chama efeito colateral (side effect), a função setPrice é uma função impura.

const setPrice = product => {
  return { ...product, price: 73 }
}
const product = { name: 'Instant Kung Foo.' }
const newProduct = setPrice(product)
product.price == 73 // false
newProduct.price == 73 // true

Agora a função setPrice retorna uma cópia rasa (shallow copy) de product que recebeu como argumento, acrescentando ou modificando a propriedade price. Esse procedimento obriga a criação de uma nova variável newProduct, isso acontece pois const foi utilizado, o próximo exemplo usa let.

Este fluxo pode incomodar um pouco, normalmente esta abordagem não é necessária, usa-se técnicas como pipe e compose.

Funções Puras

Funções puras (pure functions) andam ao lado da imutabilidade, na prática podemos dizer que uma não existe sem a outra.

Entende-se como pura a função que sempre devolve o mesmo resultado para um mesmo argumento, não importando a quantidade de vezes que ela é chamada, sem causar efeitos coletareis (side effects).

Parece e é obvio, porém, infelizmente ainda causa dúvidas para alguns programadores. Essa técnica exige um pouco de esforço por parte do programador, ele tem que explicitamente optar por usa-la.
Vajamos o seguinte exemplo:

// impure.js
let counter = 0
const addToCounter =  value => {
  counter = counter + value
}
// pure.js
const sum = (x, y)  => x + y
let counter = 0
counter = sum(counter, 10)

Este é um dos primeiros exemplos usados para descrever uma função impura, é bem óbvio. Porém sua simplicidade também dificulta sua adoção, sabemos que um programa real é mais complexo do que essa função.

const request = params => {
  if (params.client) {
    params.client_id = params.client.id
    delete params.client
  }
  return http.get('/', params)
}

O exemplo anterior é mais próximo a uma aplicação real. Temos a função request que recebe params, caso params.client exista, params é modificado.

A função request gera um efeito colateral gravíssimo, é impossível determinar a instabilidade e consequentemente bugs que essa função causa para quem a chamar.

const request = params => {
  const options = { ...params }

  if (options.client) {
    options.client_id = options.client.id
    delete options.client
  }
  return http.get('/', options)
}

Com esta mudança o problema foi resolvido, params não é mais modificado, o procedimento agora é aplicado a uma cópia dele. Porém, ainda há como melhorar esta função.

const parseRequestParams = params => {
  const data = { ...params }
  if (data.client) {
    data.client_id = data.client.id
    delete data.client
  }
  return data
}
const request = params => {
  const options = parseRequestParams(params)
  return http.get('/', options)
}

Toda a lógica de tratamento dos parâmetros foi isolada em parseRequestParams. A função passa a ser mais objetiva, delegando parte da lógica a outra função, uma função mais especializada. Isso não apenas melhora a leitura como permite criar testes de unidade com maior cobertura de possibilidades.

Uma linha, um comando, uma função.

A função parseRequestParams ainda pode evoluir ao utilizar técnicas com pipe e compose. A biblioteca ramda fornece essas e várias funções úteis para ajudar na implementação dessas técnicas.

import { compose, omit } from 'ramda'

const parseClientInRequestParams = params => {
  if (!params.client) {
    return params
  }

  return {
    ...omit(['client'], params),
    client_id: params.client.id
  }
}

const parseUserInRequestParams = params => {
  if (!params.user) {
    return params
  }

  return {
    ...omit(['user'], params),
    user_id: params.user.id
  }
}

const parseRequestParams = compose(parseClientInRequestParams, parseUserInRequestParams)

As funções parseClientInRequestParams e parseUserInRequestParams ficaram muito similares, podemos simplifica-las.

import { compose, omit, has, path } from 'ramda'
const createParseEntityInRequestParams = key => {
  return params => {
    if (!has(key, params)) {
      return params
    }
    const id = path([key, 'id'], params)
    return {
      ...omit([key], params),
      [`${key}_id`]: id
    }
  }
}
const parseClientInRequestParams = createParseEntityInRequestParams('client')

const parseUserInRequestParams = createParseEntityInRequestParams('user')

A função createParseEntityinRequestParams retorna uma função que funciona exatamente como as implementações anteriores de parseClientInRequestParams e parseUserInRequestParams.

Receber e retornar funções só é possível pois funções são Cidadãos de Primeira-Classe (First-class citizens) no JavaScript, são tratadas como valores.

Com o tempo mais padrões desses vão surgindo e se torna natural o uso de funções puras e factory functions. É um nível de reuso muito grande e de extrema flexibilidade.

Encapsulando Fluxos Impuros

Infelizmente não é viável criar uma aplicação que não lide com fluxos impuros. Operações que dependem de i/o, disco, rede, banco de dados… São operações com impuras e muitas vezes vão produzir efeitos colaterais.

Quando falamos de programação funcional, não é raro termos como monads aparecerem. Eles dão origem a muita confusão, em especial para quem ainda esta apenas começando com programação funcional.

Este artigo não vai tratar de monads, e sim de uma abordagem simplista para essas situações.

const request = params => {
  const options = parseRequestParams(params)
  return http.get('/', options)
}

Reaproveitando o exemplo anterior, temos a função request. Por mais que ela não gera mais um efeito colateral direto ela retorna uma promessa. Existe uma discussão sobre a “pureza” de uma função que retorna uma promessa, a verdade é que ela poderá ter resultados diferentes mesmo que os argumentos sejam os mesmos, isso torna ela uma função impura.

Sendo ela uma função pura ou não, há um problema mais “grave”, o fato dessa função depender de http para funcionar. Assumimos que http é uma global, provavelmente uma instância do axios. Justamente por ser global que temos um problema na hora de testar esta função.

Depender de estados globais prejudica muito o processo de testes, pois é necessário recriar toda uma camada de ambiente para que o teste seja possível, além de usar técnicas sofisticadas de mocking.

A solução é simples, injetar http em request.

const request = (http, params) => {
  const options = parseRequestParams(params)
  return http.get('/', options)
}

Isso pode ser particularmente verboso na hora de utilizar, porém com técnicas de injeção de dependências isso passa a ser simples e prático. Os links abaixo demonstram algumas técnicas que vão ajudar.

Este artigo possui um objetivo subliminar, introduzir o leitor a programação funcional sem que ele perceba. Todo o conteúdo aqui apresentado faz parte das técnicas e fluxos de programação funcional com JavaScript.

Quando se fala de programação funcional muito se fala de lambda, functors, monads e outros termos… Programação funcional possui diversas camadas e convive bem com outros paradigmas.

Seguir os princípios da programação funcional é uma das melhores maneiras de se obter um código limpo e de qualidade.

Em minha concepção pessoal um código de qualidade é um código testável. Talvez a maior dificuldade em se implementar testes seja justamente escrever código testável. Imutabilidade e funções puras são os primeiros passos.

Este artigo foi originalmente postado em 2018-12-30, no Medium

Se quiser saber mais sobre meu trabalho visite dev.to/codecasts ou blog.codecasts.com.br. Assine nosso canal no YouTube, lá você vai ver vídeos sobre JavaScript, jQuery, Gulp, ES6, Vue.JS e muito mais. Também não deixe de entrar em contato pelo nosso grupo no Telegram

Escalando e performando aplicações Node.js

Vinicius Reis — Sat, 14 Sep 2019 21:13:41 +0000

Hoje Node.js é uma das plataformas de desenvolvimento mais utilizadas no mundo. Seu ecossistema é vasto e poderoso e sua performance não é nada ruim.

Como não existe bala de prata, Node.js possui pontos de atenção, características que quando não observadas podem prejudicar a performance de aplicações criadas com ele.

Single Tread e código bloqueante

Muitos já devem saber, porém, é importante frisar, Node.js é single tread, mesmo que existam operações async (obrigado libuv) , algumas operações são consideradas bloqueantes e travam toda e qualquer execução de código.

Neste exemplo, usamos o console.time para contabilizar a execução de alguns trechos de código.

Há basicamente duas operações neste código, uma assíncrona com setTimeout, e outra síncrona, na implementação da função sleep. A parte assíncrona deste código deveria ser executada em 1 segundo, porém no resultado dos timers , o código só executou depois de 3 segundos, depois que a parte síncrona do código executou.

Para entender melhor este comportamento, leia sobre event loop.

Isso aconteceu, pois a tread do Node/JS ficou travada em uma única operação, uma operação bloqueante.

Operações bloqueantes

No exemplo anterior foi possível ter uma ideia entender que while é uma operação bloqueante e qual o impacto desse tipo de operação na aplicação. Além do while outras estruturas e funções também são bloqueantes. for, Array.prototype.forEach, Array.prototype.map, Array.prototype.reduce entre outras.

Podemos assumir que todo loop é uma operação bloqueante.

Uma única operação bloqueante tem um enorme potencial destrutivo em uma aplicação http.

Um servidor http extremamente simples, para testar sua performance a ferramenta siege será utilizada.

siege http://localhost:7337/ -b -i -t 10s

Durante 10 segundos o servidor http foi capaz de receber 51.415 requisições com correferência de 25. Abaixo alguns _logs das requisições

Evidentemente este é um ótimo resultado.

Na próxima imagem a rota agora passa a executar uma operação bloqueante por 500ms.

Novamente o teste de performance com o siege.

Durante 10 segundos 25 processos concorrentes conseguiram realizar com sucesso apenas 18 requisições. É uma diminuição drástica se comparado ao teste anterior. Abaixo alguns logs dos requests.

Cada requisição levou ao menos 500ms para ser respondida. É possível ver que o servidor http recebeu 43 requisições, porém, o teste terminou antes que do node concluir o processamento das requisições.

O node foi capaz de resolver apenas 18 requisições em 10 segundos: 500ms * 18 = 9000ms = 9s Todas as outras requisições ficaram "presas".

Este é o preço de executar operações síncronas, bloqueantes em servidores http node.

Cluster mode, múltiplos servidores.

Mesmo que esta característica seja um problema sério, há formas eficientes de contorna-la.

Node possui um módulo chamado cluster. Este módulo permite criar forks do seu processo/servidor, atuando como um load balancer.

Você pode aprender mais sobre este módulo aqui

Neste artigo não vamos falar diretamente do cluster mode, mas de uma ferramenta que usa ele para prover uma série de recursos úteis que melhoram não só a performance como a saúde da aplicação.

PM2

PM2, ou Process Manager 2 é uma ferramenta indispensável na hora de colocar uma aplicação node em produção.

É possível destacar dois principais recursos do PM2, dentre vários outros.

Monitoramento do processo

O PM2 observa cada processo iniciado com ele, e caso o processo morra, ele mesmo reinicia o processo, sem a nenhuma intervenção humana.

Este recurso é extremamente útil para garantir que a aplicação não saia do ar caso alguma exceção seja disparada e não tratada.

Múltiplos processos por aplicação

Além de manter a aplicação viva, o PM2 consegue subir mais de um processo por aplicação. Dessa forma contornamos os problemas citados neste artigo.

Outra coisa interessante é poder subir mais de uma aplicação com o PM2. Se a aplicação http precisa de algum outro processo paralelo dando suporte, como um consumidor de filas, é possível ter total controle sobre isso.

PM2 em ação

Na documentação do PM2 é possível encontrar como se instala ele e todas as suas opções de configuração. Abaixo é possível ver o resultado do PM2 sendo utilizado em cluster mode, neste exemplo foram iniciados 5 processos.

pm2 start index.js -i 5

Nestas condições o servidor http foi capaz de responder a 95 requisições em 10 segundos, um valor maior que os 18 do teste anterior.

Agora o mesmo teste com 10 processos.

pm2 start index.js -i 10

Agora o serviço foi capaz de responder 180 requisições. O próximo exemplo será com 20 processos e em seguida com 40.

pm2 start index.js -i 20

pm2 start index.js -i 40

Com 20 foi possível dobrar a quantidade de requisições, porém, com 40 processos não. Isso acontece simplesmente porque os processos começam a concorrer cada vez mais pelo processador.

Ambiente de produção

Neste exemplo foi utilizado uma maquina com 8 núcleos de processamento e 13Gb de memória RAM. Estes valores são superiores a muitos servidores comuns. Por isso a simples escala de processos não é o suficiente, é importante ter isso em mente na hora de construir uma aplicação. Em muitos momentos é necessário utilizar de escala horizontal.

A quantidade de processos por núcleo de processamento do servidor é algo que varia de aplicação para aplicação, então o ideal é fazer testes e identificar como extrair o máximo da máquina sem deixa-la em "stress".

Soluções como auto scaling + docker são altamente recomendadas.

Conclusão

Mesmo Node.js sendo single-tread é possivel tirar proveito dos vários núcleos do processador. Há também um módulo para lidar com treads, elevando as possibilidades.

Este não é o único aspecto que deve ser levado em consideração quando se trabalha com aplicações Node.js, então não se limite a este artigo e as informações contidas aqui.

Performance pura e simplesmente não é tudo, código bem escrito e testado muitas vezes são mais importantes. Até a forma como a aplicação é colocada em produção é importante.

Ao focar em entregar algo de qualidade, seguindo boas práticas de escrita e organização muitas coisas relacionadas a performance são resolvidas logo no começo.

Mantendo projetos Node/JS atualizados

Vinicius Reis — Tue, 02 Apr 2019 20:22:48 +0000

Ter pacotes de terceiros em nosso projeto é algo comum. Porém mante-los atualizados, infelizmente, não faz parte da rotina de muitos profissionais. Negligenciar esse processo pode acarretar em muitos problemas no futuro.

Este artigo trata dos motivos e estratégias como manter as dependências dos projetos sempre atualizadas.

Motivação

Software não é algo estático, esta em constante mudança e evolução. O mesmo se aplica as dependências que utilizamos em nossos projetos. E como dependências temos não apenas pacotes/código de terceiros, mas também a própria plataforma/linguagem que utilizamos.

Linguagem/Plataforma

Tão importante quanto manter a base de código atualizada, é manter a linguagem/plataforma que esta sendo utilizada atualizada.
O node monitora sua performance ao longo do tempo, garantindo que cada versão esta com mais performance ou que não houve regressão na performance. Sem contar todas as brechas de segurança que são corrigidas a cada nova versão.

Isso significa que manter o Node.js atualizado fornece mais performance e segurança.

Pacotes de terceiros

Manter o projeto atualizado garante que o projeto não irá sofrer com esse bugs e potenciais falhas de segurança. Além de potenciais ajustes que melhoram a performance de alguma coisa do pacote.

É importante lembrar que pacotes também tem dependências, elas também podem e precisam ser atualizadas.
Identificar que um pacote esta com suas dependências desatualizadas, é uma boa possibilidade de contribuição. Não é incomum brechas de segurança justamente em cenários como esses.

O NPM mantém uma lista de vulnerabilidades detectadas além do próprio npm possuir um recurso que analisa o package.json do projeto em busca de problemas. o Yarn possui um recurso similar.

Também é possível usar ferramentas que verificam automaticamente e constantemente o projeto.
O snyk.io é uma delas, com suporte a várias linguagens.

Frequência

Em um mundo ideal todos os dias os projetos seriam verificados sobre possíveis atualizações.
Porém não são todos os projetos que possuem recursos para usar ferramentas que automaticamente analisam isso, como greenkeeper.io e renovatebot.com

Uma forma para se manter uma boa frequência de verificações é fazer isso sempre que for mexer no projeto. Porém, há projetos que podem ficar várias semanas sem uma modificação. Para esses casos uma rotina recorrente de verificações é necessária.

Talvez um tarefa da sprint só para isso, a cada 15 dias.

Break changes, quebra de versão, incompatibilidades...

Não é incomum as dependências de um projeto mudarem de tal forma que seja necessário alguma mudança no código do projeto, um processo de migração ou adequação.
Em geral é o maior problema com atualizações, porém há formas de se lidar com quebras de versões.

Manter a frequência de verificação de atualizações garante um baixo acumulo de atualizações, e com isso uma maior facilidade de lidar com essas quebras.

Versionamento Semântico (Semantic Version)

A melhor forma de avaliar a compatibilidade entre as versões de uma ferramenta é o semver.
Dependências que seguem essa metodologia de versionamento deixam clara a compatibilidade entre suas versões. É necessário cuidado com ferramentas que não seguem esse modelo de versionamento, pois é impossível prever possíveis incompatibilidades.



Dado um número de versão MAJOR.MINOR.PATCH, incremente a:

1.  versão Maior(MAJOR): quando fizer mudanças incompatíveis na API,
2.  versão Menor(MINOR): quando adicionar funcionalidades mantendo compatibilidade, e
3.  versão de Correção(PATCH): quando corrigir falhas mantendo compatibilidade.

Rótulos adicionais para pré-lançamento(pre-release) e metadados de construção(build) estão disponíveis como extensão ao formato MAJOR.MINOR.PATCH.

Changelogs / Release Notes

É a melhor forma de documentar a evolução de um pacote ou ferramenta ao longo do tempo. Changelogs mantém um histórico de mudanças, além de possíveis quebras de versão. É importantíssimo sempre verificar essas anotações quando se atualiza alguma dependência.
Algumas dependências além do changelog, mantém um release notes (notas de lançamento) para cada nova versão. As vezes esse release notes é usado apenas em caso de mudanças mais expressivas.

Com base nesses documentos, é possível não apenas prevenir de quebras de versões inconvenientes, como também saber de novos recursos que podem ser relevantes ao projeto.

Quando há uma quebra de versão que impacte o projeto, nem sempre é algo que possa ser modificado/ajustado naquele momento. Porém, ao obter essa informação é possível se programar para faze-lo em outro momento mais propício.

Se você é um mantenedor de algum pacote, não deixe de gerar changelogs, no minimo documente os releases de novas versões.
Há ferramentas criadas para ajudar nesse processo.

Testes Automatizados

Testes ainda serão a melhor forma de garantir que ao atualizar alguma dependência o projeto continuará funcionando como o previsto. A necessidade de se manter o projeto atualizado e livre de riscos só reforçam essa necessidade.

Testes automatizados infelizmente não são uma realidade para muitos profissionais e empresas, por diversos motivos.
Não é o objetivo deste artigo se aprofundar neste tópico, porém uma dica pode ser dada: focar o esforço em aprender a escrever código testável, esta sim é a maior dificuldade de quem ainda não sabe como trabalhar com testes.

Como atualizar as dependências

Não é necessário verificar manualmente dependência por dependência. Tanto o yarn quanto o npm possuem ferramental para isso.



yarn upgrade
npm update

O yarn possui mais opções para esse processo



yarn upgrade --scope @vue --latest
yarn upgrade left-pad --pattern "gulp|grunt"
yarn upgrade-interactive
yarn upgrade-interactive --latest

O mais interessante é o yarn upgrade-interactive seguido do argumento --latest. Esta combinação exibe uma lista interativa com as últimas versões disponíveis das dependências do package.json.

Entendendo o que é GraphQL através de exemplos

Vinicius Reis — Mon, 01 Apr 2019 20:35:03 +0000

Mesmo com a popularidade do GraphQL, dúvidas sobre o que ele é, e o que resolve são comuns. Neste artigo pretendo explicar a partir de exemplos o que é GraphQL e qual o seu objetivo.

O que não é GraphQL?

Talvez este não seja o tópico que você esperava encontrar, e algumas das coisas aqui pareçam absurdas, mas acredite há pessoas que pensam ou já pensaram isso sobre GraphQL.

Publicado originalmente em 10/03/2019

GraphQL não é um banco de dados

GraphQL não tem nenhuma relação com o banco de dados, e não é um ORM. Ele nem precisa de um banco de dados para funcionar.
Talvez essa associação exista quando se ouve que ele é uma Query Language.

GraphQL não é um framework

Não se trata de mais um framework, em sua essência GraphQL é uma especificação que possui implementações em diversas linguagens.

GraphQL não é exclusivo para HTTP/APIs

GraphQL não é simplesmente uma nova forma de se criar APIs com HTTP.

Na verdade ele nem usa verbos HTTP, ele desconhece completamente esta camada. GraphQL não se limita ao contexto de aplicações HTTP.

O que é GraphQL?

‘Uma Query Language.’

Infelizmente é uma resposta simples e pouco objetiva. Mesmo que GraphQL em si seja algo simples, por vários motivos a explicação do que ele é não é a mais simples.

O objetivo deste artigo não é entrar nas nuances mais técnicas, porém é necessário explicar alguns conceitos chave.

Tipos e Schema

GraphQL é estaticamente tipado, tudo nele precisa de um tipo associado, e esses tipos formam um schema.

É a partir desse schema que as queries são executadas e consequentemente validadas, tanto entrada quanto saída.

Há alguns tipos base, como String, Int, Float, ID e Boolean. Eles são conhecidos como Scalar Types, e é possível criar os seus próprios tipos, escalares e objetos.

Segue o exemplo da criação de dois tipos, User e Address

Os tipos acompanhados de ! informam que não aceitam null como valor.

O mais interessante deste exemplo é o field address de User, ele aponta para outro tipo, o Address. Podemos assumir que há um relacionamento entre User e Address.

Como esse relacionamento é feito? Não importa, GraphQL não entrega detalhes de implementação, o field address, pode vir de qualquer lugar seja, outro banco, arquivo ou API.

Para que consultas sejam feitas, há um tipo especial no schema, ele é a “porta de entrada”

Aqui temos uma idéia mais completa e elaborada. Em schema informamos que o tipo Query é responsável pela “entrada” das queries, este tipo também costuma ser conhecido como RootQuery.

Em Query temos dois fields, Users e User. Podemos ver também o uso de argumentos em fields, significa que para consumir aquele dado, é necessário passar esses argumentos caso eles sejam obrigatórias.

Apenas User tem uuid com argumento obrigatório, em Users, pagination e search não são obrigatórios.

Neste exemplo de query o recurso User é consumido, passando como argumento uuid. Com base na assinatura do field, se um tipo User não for retornado, o GraphQL informará erro.

Ainda no exemplo antes desse, em Users, o argumento pagination recebe também um tipo como argumento, e como resposta não temos uma lista de User, e sim outro tipo UsersResource.

GraphQL não tem recursos de paginação ou qualquer coisa do gênero, isso deve ser feito através do design do schema que está sendo criado. Este é um dos design possíveis para esse tipo de situação.

Resolvers

A partir daqui o artigo passa a focar na implementação em JavaScript do GraphQL, mas os conceitos são compartilhados entre as outras implementações.

Resolvers são funções responsáveis por, como o nome sugere, revolver um pedido e devolver o dado solicitado. Abaixo segue o exemplo de um possível resolver para Query.User.

É uma função extremamente simples, ela recebe três argumentos: _root_, _args_ e _context_.

Como é um resolver raiz, root não tem valor. Mais sobre ele em seguida.

O segundo parâmetro (args) contém um objeto com o que foi passado para o field quando a query foi feita, no exemplo em questão, um objeto com a propriedade uuid.

O terceiro parâmetro (context) é controlado pela nossa instância do GraphQL, todos os resolvers recebem o mesmo context. Ele é extremamente útil para compartilhar coisas como usuário atual, serviços e coisas como conexão com o banco de dados.

Neste exemplo o uuid de args é utilizado em conjunto do knex de context, e com isso um registro é recuperado do banco de dados.

O retorno de um resolver é uma promessa, o GraphQL espera a resolução dessas promessas para devolver os resultados obtidos. No exemplo acima, se o resultado não for satisfatório o GraphQL informa que houve um erro. Porém, é possível gerar erros mais assertivos.

Agora um erro mais preciso será recebido por quem executou essa query.

Relacionamentos

Como visto anteriormente, é possível estabelecer um relacionamento entre tipos no GraphQL. Foi estabelecido um relacionamento entre User e Address.

Temos duas formas de chegar até o tipo User, através de Query.Userou Query.Users.records. O primeiro devolve apenas um User, o outro uma lista de User, cada um com seu respectivo resolver. Isso só tem importância para se entender que é necessário criar apenas um resolver para o field address.

Este é o resolver User.address. Não importa de onde o tipo User foi recuperado, há apenas um resolver para address. Isso significa que uma vez que isso seja mapeado, todo o seu schema tira proveito disso.

Em userAddressResolver root é o User em questão, dele é extraído a propriedade zipcode. Em seguida zipcode é passado como argumento para zipcodeService . Os detalhes de implementação dele não importam, porém é possivel imaginar que este serviço se comunique com uma API externa que devolve informações baseadas no zipcode.

Vamos acrescentar mais alguns tipos ao nosso schema.

Agora há o tipo Photo e um novo field em Query, o featuredPhotos.

Repare no field url, ele devolve o tipo Url, este não é um tipo nativo do GraphQL, foi colocado apenas como exemplo que é possível criar tipos como esse.

Uma vez que Photo tenha um relacionamento com User, é possível fazer a seguinte query:

Visão geral

Ao adotar GraphQL em sua aplicação, você terá inicialmente uma curva levemente mais lenta no começo, porém rapidamente o valor agregado do GraphQL se destaca, o desenvolvimento do back-end e do front-end se torna mais ágil e dinâmico, menos idas e voltas.

A maior dificuldade do GraphQL não está em sua implementação e uso, e sim no design dele. Ele não tem os problemas de design que uma aplicação Rest possui, porém trás novos desafios.

Ainda não há um consenso difundido sobre padrões de design com GraphQL, mas há uma grande fonte de exemplos e cases.

Pessoalmente acredito na qualidade e versatilidade do GraphQL frente a soluções Rest. Não me sinto mais confortável em criar uma aplicação que não possua o GraphQL como API.

Entre os muitos usos do GraphQL é utilizado como front-end de outros back-end, isso é conhecido como Backend-For-Frontend. Imagine a complexidade de um front-end ter que acessar várias APIs distintas para conseguir uma informação, GraphQL atende muito bem a esses cenários.

E o Rest?

É possível argumentar que com a ajuda de um ORM + algum padrão mirabolante de requests, é possível se obter estes resultados sem o uso do GraphQL

Abaixo alguns destaques que reforçam a adoção do GraphQL

Existe padrão

Na grande maioria dos casos você ou sua equipe iriam inventar algum padrão/método ou aplicar alguma biblioteca para emular esse comportamento (respostas personalizadas, relacionamentos…)

Porém há uma equipe grande e séria por trás da especificação do GraphQL, este artigo não cobre metade das possibilidades.

Auto-documentação

Enquanto seria necessário aplicar ferramentas que geram documentações compatíveis com swagger e similares, GraphQL possui documentação automática, além de um ambiente de testes muito produtivo.

Auto-validação

O sistema de tipos do GraphQL já funciona como um processo de validação, tanto de entrada quanto de saída. Também existe a possibilidade de integração com editores de código que validam as queries da aplicação, além de linhas de comando que podem ser integradas em processos de CI/CD

Realtime

A especificação do GraphQL já prevê real-time. Não são todas as implementações que são compatíveis, porém ela existe e não é complexa.

Isso abre muitas possibilidades antes inexistentes para alguns projetos ou equipes.

facebook/graphql

Iniciando com GraphQL

Este artigo não demonstra como começar com GraphQL, por isso, abaixo está uma lista de recursos úteis para se começar com GraphQL.

Lembrando que GraphQL é implementado em várias linguagens, então escolha a que for mais amigável para você e comece seus experimentos.

Interessado em aprender mais sobre GraphQL? Entre no nosso grupo no Telegram https://t.me/GraphQLBrasil

Não deixe de compartilhar e comentar este artigo. Deixe nos comentários sua opinião sobre esse assunto, pontos que você concorda ou discorda. Vamos agregar mais conhecimento!

Se quiser saber mais sobre meu trabalho visite blog.codecasts.com.br. Assine nosso canal no YouTube, lá você vai ver vídeos sobre JavaScript, jQuery, Gulp, ES6, Vue.JS e muito mais. Também não deixe de entrar em contato pelo nosso grupo no Telegram

that’s all folks