GraphQL: lições aprendidas em produção

Estamos em 2020. Os vossos equipa inclina-se cada vez mais para a construção de aplicações de página única ou, pelo menos, para a inclusão de componentes ricos em aplicações regulares de várias páginas. O [GraphQL](https://graphql.org/) tem [mais de dois anos](https://en.wikipedia.org/wiki/GraphQL) agora, o que por JavaScript as normas do ecossistema podem ser consideradas maduras. Estávamos a sentir-nos um pouco aventureiros, por isso prescindimos das habituais APIs JSON e mergulhámos de cabeça - eis o que aprendemos.

É necessário um servidor GraphQL

Na maioria dos quadros utilizados para desenvolvimento webSe o utilizador tiver uma API JSON, as ferramentas para construir uma API JSON já existem. Pode construir uma estrutura de rotas e aceitar facilmente alguns GETs e POSTs, dando depois uma resposta JSON. Rubi sobre Carris até tem uma projeto que dispensa os habituais recursos de renderização HTML e coloca uma base sólida de APIs no seu lugar. O que se segue é que um programador experiente que utilize ferramentas modernas pode criar um backend em literalmente minutos.

O mesmo não acontece com o GraphQL. Embora existam bibliotecas de servidor para muitas línguasMesmo assim, a velocidade é prejudicada logo no início - simplesmente por ter que descobrir o que é certo para o seu ecossistema. Numa nota mais pessoal, também não gosto do termo "servidor" usado para descrever uma biblioteca que pode ser introduzida num projeto.

Só há um ponto final

Ao longo dos anos, habituámo-nos a uma forma particular de pensar sobre a estrutura da API. No nível mais básico, simplesmente seguimos as práticas REST. Isso significava criar vários pontos de extremidade por modelo lógico na nossa aplicação. É uma estrutura fácil de entender tanto para os autores da API quanto para os consumidores. Ela também produz métodos bem escopo no backend, fazendo com que o raciocínio sobre a código tão fácil como a própria API. Esta estrutura também é fácil de nomear, por exemplo, para efeitos de Controlo de versões da API.

O GraphQL utiliza apenas um único ponto de extremidade, normalmente /graphql. Cada pedido à sua API chegará como um pedido POST a esse ponto final e, a partir daí, é da responsabilidade do servidor GraphQL descobrir o que o cliente pretende e responder adequadamente.

À primeira vista, parece difícil de manejar: imagine tentar fazer tudo numa API JSON com um único ponto final! No entanto, rapidamente começa a fazer sentido à medida que a sua API amadurece e algumas coisas são substituídas por outras. A depreciação nas APIs clássicas é normalmente feita ao nível do namespace, passando de v1 para v2. O GraphQL oferece muito mais controlo, até à eliminação de um único campo. Imagine ser capaz de dizer a um consumidor da API REST que você não quer que ele use o campo nome e utilizar o campo nome_de_fantasia em vez disso! Acontece que o que parecia pesado no início é, na verdade, uma das melhores funcionalidades.

Tudo é dactilografado

O JSON não tem muitas opções de digitação. Existem strings, números, arrays e objectos. Além disso, você está sem sorte. Por outro lado, no GraphQL, tudo começa e termina com tipos, já que até mesmo a raiz Query e Mutation são apenas isso - tipos. A DSL do GraphQL impõe a verificação de tipos tanto no servidor quanto no cliente, prevenindo todos os tipos de surpresas desagradáveis.

Isto é muito importante, especialmente porque os SPAs são cada vez mais verificados por tipo, seja usando TypeScript ou alternativas como Flow. O GraphQL facilita a introdução de tipos complexos e compostos para além dos valores predefinidos e torna-se rapidamente uma segunda natureza para os programadores, tanto no backend como no frontend.

Ler mais: Testando o JavaScript... com Ruby?!

Os documentos estão incorporados

Em uma API JSON clássica, a documentação pode ser uma reflexão tardia. E mesmo que não o seja, há muitos métodos por onde escolher. Será que usamos algum esquema como OpenAPI? Depois convertemo-lo para um formato legível por humanos com ferramentas como o Swagger? Ou simplesmente despejamos um monte de ficheiros Markdown algures? Apesar de este problema ter sido resolvido várias vezes, continua a exigir um pensamento consciente e esforço da equipa - primeiro para construir os documentos, depois para os manter actualizados e divulgados. É um problema ainda mais complexo quando a API tem várias secções que só são acessíveis, por exemplo, por determinados papéis de utilizador.

No GraphQL, a documentação é um cidadão de primeira classe, pois a maioria dos servidores permite documentar seus tipos e solicitações no local. Desde o início de 2018, a linguagem de definição de esquema do GraphQL passou a fazer parte da especificação oficial, portanto, há precisamente uma maneira de documentar uma API GraphQL. Além disso, uma vez que o GraphQL permite definir a visibilidade de certas partes do gráfico, os utilizadores que não o devem fazer são automaticamente impedidos de ver documentos para o que não podem aceder. Ter a decisão tomada e diretrizes claras tem sido uma grande vantagem para a equipa.

Existem apenas dois tipos de ação

Em contraste com GET, POST, PUT, PATCH e DELETE do HTTP, existem apenas dois tipos de ação no GraphQL: Consultas e Mutações. A principal diferença é que as Mutações podem e irão alterar o estado do sistema e as Consultas irão apenas ler passivamente os dados.

Admito que ainda estou indeciso em relação a esta questão. Gosto da infinidade de verbos do HTTP para interagir com recursos e poder usar a ferramenta certa para o trabalho. O GraphQL facilita o tratamento dos casos em que qualquer um dos verbos HTTP não se encaixa exatamente, mas incorre na penalidade de ter que pensar sobre o que uma mutação específica realmente afetará. Também se pode dizer que, uma vez que não existe uma convenção de nomenclatura padrão incorporada, terá de elaborar guias de estilo internos ou arriscar-se a construir uma confusão inconsistente.

É praticamente necessário ter um cliente

Interagir com APIs REST sobre HTTP é super fácil no JavaScript, ainda mais usando o moderno buscar API. Em contrapartida, para o GraphQL, é necessário utilizar uma biblioteca de cliente se pretender um desempenho realmente decente. Não é impossível interagir com uma API GraphQL usando apenas o JavaScript básico - afinal, são apenas solicitações POST. No entanto, usar apenas tecnologias da Web de longa data, como o cache de solicitações para chamadas de API comuns, não funcionará, pois as solicitações POST geralmente não são armazenadas em cache.

Todo cliente GraphQL razoável implementa um mecanismo de cache de resultados do lado do cliente, e muitos outros recursos. Graças a todas essas escolhas, fazer uma configuração manual para um cliente GraphQL no nível de entrada é uma tarefa completamente estupefata. Ao começar com GraphQL eu recomendo especialmente dar uma olhada em Apollo-Boost uma vez que vem com predefinições muito razoáveis.

O cliente seleciona os dados

Já todos passámos por isso: retiramos uma lista de dados da API e falta-lhe um campo crucial sobre um modelo relacionado. Em seguida, implementamos um hack que envolve N+1 pedidos enquanto nos queixamos aos programadores de backend que se apressam a adicioná-lo rapidamente. Isso geralmente não é o caso com uma API GraphQL bem implementada, já que podemos simplesmente mergulhar nos dados tão profundamente quanto quisermos. Precisa de ver o endereço de um cliente numa encomenda deste lote? Não é um problema - pelo menos em teoria, o que nos leva a nós para...

A complexidade é mais difícil de prever

Ao projetar o GraphQL do lado do back-end, pode ser difícil pensar em toda a profundidade que um cliente pode mergulhar no gráfico. Existem muitas maneiras de instrumentar e observar o uso do seu gráfico, e depois de deixar seus colegas de front-end brincarem por um tempo, você pode começar a ver algumas consultas longas realizando leituras bastante imaginativas no seu armazenamento de dados. Numa API REST isto é mais fácil de controlar, uma vez que se pode facilmente dizer o âmbito dos dados que serão acedidos num único pedido. Muitas vezes, essa complexidade perdida pode ser muito difícil de controlar quando é lançada na produção. Muitas vezes, também não é óbvio como escapar deste buraco que cavaram para si próprios.

As páginas numeradas são muito difíceis

Esta é uma reclamação que é realmente irônica. É possível sentir que o GraphQL foi concebido para o Facebook, olhando para a forma como o seu mecanismo de paginação funciona. As chamadas Conexões são basicamente fluxos intermináveis de arestas de gráficos, cuja navegação é feita através de cursores em vez das páginas mais clássicas. Embora seja fácil perceber como é que isso se adequa a um feed interminável de mensagens ao estilo do Facebook, se quisermos uma lista bem paginada com a possibilidade de ir, digamos, para a página 42, vamos ter muito mais dificuldade. É claro que há formas de contornar isso, mas é isso que são - soluções alternativas.

Voltaríamos a fazê-lo?

Com todas as queixas e diferenças listadas acima, provavelmente pensa que estamos a tratar o GraphQL como uma experiência que azedou e voltou diretamente para as APIs REST. Isso não é verdade. Na verdade, estamos a trabalhar para utilizar o GraphQL mais amplamente em projectos em toda a organização. É uma ótima tecnologia que tornou nosso trabalho mais fácil e melhor. No entanto, investimos inicialmente no GraphQL sem perceber completamente o tipo de dores de crescimento pelas quais passaríamos.

Se acha que o GraphQL pode ser a solução ideal para si, encorajo-o a arriscar. Dê a si mesmo muito tempo e espaço para falhar com segurança, e você estará colhendo os benefícios em pouco tempo!

Leia também:

– Como gerir eficazmente os programadores remotos? O guia para CTOs

– Python vs. Ruby? Que tecnologia deve utilizar para o desenvolvimento de produtos?

– Um guia rápido para criar e desenvolver o seu próprio mercado. O que vale a pena saber?