Integrações GraphQL e NodeJS usando o Cloud Code Functions

O GraphQL traz açúcar, tempero e tudo de bom para os desenvolvedores de API, mas é basicamente uma linguagem de consulta para que você possa especificar o que está procurando.

E se você precisar de mais business intelligence do que isso em seu aplicativo?

E se você precisar de alguma lógica junto com ele?

E se você quiser aquele módulo de módulo NPM bacana junto com ele?

Bem, aperte os cintos, pois hoje vou lhe mostrar algo muito poderoso. E com grandes poderes, vêm grandes… bem… grandes economias de tempo, grandes possibilidades, muitas coisas boas…

Se quiser saber mais sobre o GraphQL, dê uma olhada neste post: O que é GraphQL

Você precisa ter esta altura para andar…

E use o Parse 3.5.0 ou superior para brincar com o GraphQL.
Vá para Server Settings (Configurações do servidor) e Manage Parse Server (Gerenciar servidor Parse) e verifique se você está usando uma versão compatível.

Nosso novo recurso brilhante: GraphQL + Funções de código de nuvem

Se você já é um usuário do Parse/Back4app, provavelmente já usou ou pelo menos ouviu falar do Cloud Code.

O Cloud Code é essencialmente um código NodeJS que é executado a partir dos servidores de aplicativos do Back4app em vez de nos dispositivos finais.

Isso traz algumas vantagens importantes, dependendo de suas necessidades, mas essencialmente permite que você:

• Economizar a bateria do celular

  Quando você transfere a carga pesada de processamento do dispositivo para a nuvem, o processamento intenso não será feito no dispositivo, economizando bateria. O processamento é feito em nossos servidores e apenas o resultado final é enviado ao cliente. Não há mais um celular quente no seu bolso. Chega de “OMG esse aplicativo suga minha bateria!”.

• Economize nos planos de dados

  Então você tem uma tonelada de objetos que precisa recuperar para obter um relatório. Milhares? Milhões?
  São muitos dados que você precisa recuperar e, se não estiver usando WiFi, é melhor fazer um upgrade no plano de dados do celular.
  Todos sabemos que o plano de dados é bastante caro (ninguém mais paga por mensagens SMS, certo?), portanto, e se tivéssemos uma abordagem mais inteligente?
  E se pudéssemos obter o relatório totalmente calculado na nuvem e recuperar apenas o último resultado para o dispositivo? Uma carga útil menor que consumiria muito menos de seu plano de dados e também seria executada mais rapidamente?
  Parece incrível? É isso que o Cloud Code faz…

• Obtenha uma implementação de código mais rápida

  Antigamente, os desenvolvedores precisavam republicar seus softwares nas lojas de aplicativos. Naquela época, isso costumava ser uma loteria: se um revisor fosse mais rápido, seu aplicativo estaria disponível para os usuários no mesmo dia. Com um revisor mais lento ou exigente, seu aplicativo poderia levar semanas para ser publicado. Se ele fosse publicado.
  Por que arriscar isso?
  Entregue somente a parte de front-end do seu aplicativo para as lojas de aplicativos e deixe o máximo possível de lógica para ser chamada de Cloud Code.
  Precisa fazer uma pequena alteração na lógica? Ou uma enorme? Não tem problema.
  Altere o Cloud Code, implemente-o novamente e você estará como novo. Sem revisões de um cara de outro lugar e com disponibilidade instantânea para seus clientes.

Mas, novamente… e quanto ao GraphQL?

O GraphQL permite que você faça consultas. Você pode fazer consultas muito inteligentes, mas apenas consultas.

Quando nosso CEO, Davi, estava discutindo como torná-lo mais inteligente, a integração com o Cloud Code Functions parecia ser apenas lógica: você tem o melhor dos dois mundos! O poder e a inteligência do Cloud Code Functions E a facilidade e a facilidade de manutenção do GraphQL.

Por meio do nosso novo recurso, você pode estender os tipos de GraphQL para executar o Cloud Code Functions e recuperar seus resultados.

Você pode aplicar qualquer lógica de negócios que possa imaginar em suas funções de código de nuvem, incluir módulos NPM com elas e consultar tudo isso com o GraphQL.

Chega de conversa. Vamos colocar as mãos na massa…

As classes e os objetos que usaremos

Para esta postagem, criei duas classes distintas: Employee e Pet, que conterão os funcionários da Back4app e seus respectivos animais de estimação.

Um Employee tem as seguintes propriedades:

• nome (String)
• idade (Number)
• e-mail (String)
• cargo (String)
• hasThisPet (Ponteiro para a classe Pet)

Um Pet tem as seguintes propriedades:

• nome (String)
• espécie (String)

E algumas funções de código de nuvem

E para nossas funções de código de nuvem, escreverei um arquivo chamado main.js e incluirei o seguinte código.

Ele tem cinco funções de código de nuvem totalmente comentadas que servirão:

• checkGraphQLSupport
  verificar se o aplicativo tem suporte para GraphQL
• retrieveFirstEmployeeByName (recuperar primeiro funcionário por nome)
  recuperar todos os detalhes do primeiro funcionário encontrado no banco de dados com um determinado nome
• retrieveAllEmployees (recuperar todos os funcionários)
  recupera todos os detalhes sobre todos os funcionários
• retrieveOnwerOfPetByName
  recuperar os detalhes de um funcionário que tem um animal de estimação com um determinado nome
• retrieveEmployeeByNameWithPet (recuperar funcionário com animal de estimação)
  recuperar todos os detalhes de um funcionário e seu animal de estimação

Parse.Cloud.define("checkGraphQLSupport", async req => {
  /*
    Essa função retorna se o aplicativo tem suporte para GraphQL. 
    O parseGraphQLServer é verdadeiro quando o aplicativo tem suporte, ou falso, caso contrário
  */
  se (parseGraphQLServer){
    retorna "Este aplicativo tem suporte para GraphQL";
  } else {
    return "Este aplicativo não tem suporte ao GraphQL. Talvez seja a versão errada do Parse?";
  }
});

Parse.Cloud.define("retrieveFirstEmployeeByName", async req => {
  /*
    Essa função recupera o primeiro funcionário encontrado com um determinado nome.
    Todas as propriedades do Employee são recuperadas.
    Apenas um Employee é retornado se houver mais de um no banco de dados.
    Se não houver nenhum funcionário, será recuperado o valor nulo.
  */
  const query = new Parse.Query("Employees"); 
  query.equalTo("name", req.params.name);
  const result = await query.first();
  return result;
});

Parse.Cloud.define("retrieveAllEmployees", async req => {
  /*
    Essa função recupera todos os funcionários.
    Todas as propriedades da classe Employee são recuperadas, mas somente essa classe.
    Nenhum detalhe de ponteiros ou relações é recuperado, apenas o objectId.
    Uma matriz de funcionários é retornada. Vazio se não houver funcionários.
  */
  const query = new Parse.Query("Employees"); 
  const results = await query.find();
  return results;
});

Parse.Cloud.define("retrieveOnwerOfPetByName", async req => {
  /*
    Essa função recupera as informações sobre o funcionário relacionadas a um animal de estimação,
    pelo nome do animal de estimação.
    Todas as propriedades da classe Employee são recuperadas.
    Nenhum detalhe do Pet será recuperado.
    Uma matriz de Pet é retornada. Vazio se nenhum Pet for encontrado.
  */

  // Primeiro, fazemos uma consulta para recuperar as informações sobre o animal de estimação
  const petQuery = new Parse.Query("Pet"); 
  petQuery.equalTo("name", req.params.name);
  
  // Em seguida, fazemos uma consulta para recuperar os detalhes de seu funcionário com base na propriedade hasThisPet
  let employeeQuery = new Parse.Query("Employees"); 
  employeeQuery.matchesQuery("hasThisPet", petQuery);
  const results = await employeeQuery.find();

  return results;
  
});

Parse.Cloud.define("retrieveEmployeeByNameWithPet", async req => {
  /*
    Essa função recupera as informações sobre o funcionário e seu animal de estimação relacionado,
    pelo nome do funcionário.
    Todas as propriedades da classe Employee e da classe Pet são recuperadas.
    Uma matriz de Employee é retornada, incluindo uma propriedade hasThisPet totalmente preenchida
    com as informações sobre o animal de estimação.
    Uma matriz empy é retornada se nenhum Employee for encontrado.
  */
  const query = new Parse.Query("Employees"); 
  query.equalTo("name", req.params.name);
  query.include("hasThisPet")
  const results = await query.find();
  return results;
});

Faremos o upload para o nosso Cloud Code Functions, na pasta Cloud.

Uma pequena etapa extra

As funções do Cloud Code que acabamos de publicar já podem ser usadas, mas, para que funcionem com o GraphQL, precisamos criar um arquivo chamado schema.graphql e expor essas funções.

A sintaxe é muito simples, mas precisa de atenção:

extend type Query {
 GraphQLMethodName (parameterName: parameterType): ReturnType! @resolve(to:"CloudCodeFunctionName")
}

Para o código acima, a sintaxe representa:

• GraphQLMethodName
  Esse é o nome que você chamará na sua consulta GraphQL. Ele não precisa corresponder ao nome da função do Cloud Code, mas você deve escolher algo que facilite a compreensão do que esse método faz.

• parameterName
  O nome do parâmetro que você consumirá na solicitação quando estiver dentro da função de código de nuvem. Você não precisa passar esse valor se não estiver usando parâmetros em sua função de código de nuvem.

• parameterType
  O tipo do parâmetro que você está passando. Você pode saber mais sobre esquemas e ver todas as possibilidades. Você não precisa passar isso se não estiver usando parâmetros na sua função do código de nuvem.

• ReturnType
  Este é o tipo de retorno de seu método.

• CloudCodeFunctionName
  Deve corresponder ao nome da função do código de nuvem que você forneceu no arquivo main.js, pois ele chamará esse código pelo nome da função.

Portanto, para o nosso arquivo main.js que acabamos de criar, nosso schema.graphql seria:

extend type Query {
  checkGraphQLSupport: String! @resolve(to: "checkGraphQLSupport")
  retrieveThisEmployeeByName (name:String): EmployeesClass! @resolve(to: "retrieveFirstEmployeeByName")
  giveMeAllEmployees: [EmployeesClass!]! @resolve(to: "retrieveAllEmployees")
  whichEmployeeIsOnwerOfThisPet (name:String): [EmployeesClass!]! @resolve(to: "retrieveOnwerOfPetByName")
  gatherEmployeeAndPetByEmployeeName (name:String): [EmployeesClass!]! @resolve(to: "retrieveEmployeeByNameWithPet")
}

Não é tão difícil assim, não é?

Observe que usei nomes muito extensos que não correspondem ao nome das funções do código da nuvem, apenas para que você saiba que pode renomear ao expor.

Agora, volte para a seção Cloud Code Functions do seu aplicativo e carregue esse arquivo também. Certifique-se de que ele também esteja na pasta Cloud. Você pode arrastá-lo e soltá-lo lá, se necessário.
Se você já tiver um arquivo com esse nome e não puder carregar um novo, clique com o botão direito do mouse e exclua-o antes de fazer o upload.

Implemente tudo e estamos prontos para começar:

Agora, é hora da mágica…

Vá para o console do GraphQL. Comece a digitar “query” e use a função Autocomplete (CTRL + barra de espaço no Windows, OPTION + barra de espaço no Mac) e veja a mágica acontecer:

Todos os nossos métodos estão lá e podemos consultar cada um deles. Vamos tentar um por um:

• checkGraphQLSupport

  (resolve para nossa função de código de nuvem checkGraphQLSupport)
  

• retrieveThisEmployeeByName (name:String)

  (resolve para a nossa função de código de nuvem retrieveFirstEmployeeByName)
  

• giveMeAllEmployees

  (resolve para a nossa função de código de nuvem retrieveAllEmployees)
  
  Observe no exemplo acima que as propriedades name e age foram recuperadas corretamente, mas a hasThisPet tem valores nulos para o nome e a espécie do animal de estimação.
  Isso se deve ao fato de que, nessa função de código de nuvem, não incluímos (usando o método include()) as informações sobre o animal de estimação.
  O Autocomplete nos mostrará as possibilidades, mas nenhum dado para preencher essas informações foi fornecido na Cloud Code Function.
  Consulte o exemplo gatherEmployeeAndPetByEmployeeNameresolves abaixo para ver como incluir informações.

• whichEmployeeIsOnwerOfThisPet

  (resolve para a nossa função de código de nuvem retrieveOnwerOfPetByName)
  

• gatherEmployeeAndPetByEmployeeName 

  (resolve para a nossa função de código de nuvem retrieveEmployeeByNameWithPet)
  

Suas incríveis definições foram atualizadas

É assim que você traz alguma lógica de negócios para o GraphQL.

Adoro você, 3000!

Conclusão

O GraphQL é uma linguagem de consulta e tempo de execução multiplataforma fácil e poderosa, mas, no fim das contas, é apenas uma linguagem de consulta.
Com essa novíssima integração com o Cloud Code Functions, trouxemos a você o melhor dos dois mundos, liberando o poder do Cloud Code (incluindo os módulos NPM, baby!).

Agora é com você e sua criatividade! Diga-nos o que achou e como está usando em seus projetos nos comentários abaixo!