GraphQL APIs instantâneas para MongoDB com Grafbase
Jamie Barton7 min read • Published Oct 12, 2023 • Updated Oct 12, 2023
Avalie esse Tutorial
No cenário em constante evolução do desenvolvimento web, o gerenciamento e a recuperação eficientes de dados são fundamentais para criar aplicativos dinâmicos e responsivos. O MongoDB, um banco de dados NoSQL versátil, e o GraphQL, uma poderosa linguagem de query para APIs, emergiram como uma dupla dinâmica que habilita os desenvolvedores a criar aplicativos robustos, flexíveis e de alto desempenho.
Quando combinados, MongoDB e GraphQL oferecem uma solução poderosa para desenvolvedores front-end, especialmente quando usados na borda.
Você pode estar interessado em saber a sinergia entre um banco de dados não estruturado e uma linguagem de query estruturada. Felizmente, o Grafbase oferece uma solução que combina perfeitamente ambos, aproveitando suas transformações de esquema de connector distintas.
Neste tutorial, você verá como é fácil configurar o MongoDB e o Grafbase, simplificando a introdução do GraphQL em seus aplicativos.
Você precisará do seguinte para começar:
- Uma conta com Grafbase
- Uma conta com MongoDB Atlas
- Um banco de dados com acesso à API de dados ativado
Para os fins deste tutorial, criei um cluster compartilhado gratuito com uma única implantação de banco de dados. Iremos referir-se a esta instância como seu "Data Source " mais tarde.
Localize oacesso à Atlas Data API no menuServiços dentro do painel do MongoDB Atlas e habilite o acesso deleitura/gravação:
Depois de ativado, copie o URL Endpoint e salve-o em algum lugar. Vamos precisar dela na próxima seção.
Agora navegue até Data API > Users e clique em Create API Key. Dê um nome e gere:
Copie a chave API e salve-a em algum lugar. Vamos precisar dela na próxima seção.
Por fim, navegue até as coleções deCluster e clique em Adicionar meus próprios dados para dar um nome ao seu banco de dados e à primeira coleção.
Por fim, anote a Fonte de Dados Vinculada e o Banco deDados para os quais você habilitou a API de Dados do Atlas.
Vamos começar criando um novo projeto Grafbase localmente usando a CLI.
Usaremos o executor de pacote
npx
para invocar a Grafbase CLI, o que significa que não precisamos instalar nada.1 npx grafbase init my-mongodb-api
Esse comando gerará um novo diretório chamado
my-mongodb-api
que inclui a configuração inicial do Grafbase. É seguro executar esse comando dentro de um projeto existente, como um repositório de front-end para o qual você está criando uma API do GraphQL.Você será solicitado para selecionar o formato de configuração para Grafbase. Suas opções aqui são Typescript e SDL. O Typescript SDK oferece uma melhor experiência ao desenvolvedor ao trabalhar com o SDK. Você não precisa estar usando Typescript em seu projeto frontend para usar este formato de configuração. Seu único objetivo é configurar seu back-end do Grafbase.
Antes de continuar, abra o arquivo
grafbase/.env
e adicione as variáveis de ambiente que obtivemos acima quando ativamos a API de dados:1 MONGO_ATLAS_URL= 2 MONGO_API_KEY= 3 MONGO_DATASOURCE= 4 MONGO_DATABASE=
Agora que configuramos a API de dados e estruturamos um projeto Grafbase, podemos invocar o connector Grafbase MongoDB com as credenciais obtidas anteriormente.
Abra o arquivo
grafbase/grafbase.config.ts
e atualize o conteúdo com o seguinte:1 import { config, connector, g } from '@grafbase/sdk' 2 3 const mongodb = connector.MongoDB('MongoDB', { 4 url: g.env(‘MONGO_ATLAS_URL’), 5 apiKey: g.env(‘MONGO_API_KEY’), 6 dataSource: g.env(‘MONGO_DATASOURCE’), 7 database: g.env(‘MONGO_DATABASE’) 8 }) 9 10 g.datasource(mongodb) 11 12 export default config({ 13 schema: g 14 })
No código acima, estabelecemos um link para a Atlas Data API utilizando as variáveis de ambiente que incorporamos. Em seguida, conectamos esse link ao Grafbase Edge Gateway por meio da chamada
g.datasource(mongodb)
.O connector do MongoDB permite que os desenvolvedores organizem suas collection do MongoDB de uma maneira que permita ao Grafbase gerar de forma autônoma as queries e mutações essenciais para a criação, recuperação, atualização e exclusão de documentos nessas collection.
No Grafbase, cada configuração de uma coleção é chamada de modelo ", " e você tem a flexibilidade de empregar os escalares GraphQL suportados para representar dados dentro da (s) coleção (s).
É importante considerar que, nos casos em que você possui documentos pré-existentes em sua coleção, nem todos os campos são aplicáveis a todos os documentos.
Vamos trabalhar com a suposição de que você não tem documentos existentes e deseja criar uma nova coleção para
users
. Usando o SDK TypeScript do Grafbase, podemos escrever o esquema para cada modelo de usuário. Ele se parece com o seguinte:1 const address = g.type('Address', { 2 street: g.string().mapped('street_name') 3 }) 4 5 mongodb 6 .model('User', { 7 name: g.string(), 8 email: g.string().optional(), 9 address: g.ref(address) 10 }) 11 .collection('users')
Esse esquema gerará uma API GraphQL totalmente funcional com consultas e mutações, bem como todos os tipos de entrada para paginação, ordenação e filtragem:
userCreate
– Crie um novo usuáriouserCreateMany
– Criar novos usuários em loteuserUpdate
– Atualizar um usuário existenteuserUpdateMany
– Usuários de atualização em loteuserDelete
– Excluir um usuáriouserDeleteMany
– Excluir usuários em loteuser
– Buscar um único registro de usuáriouserCollection
– Buscar vários usuários de uma collection
O MongoDB gera collections automaticamente quando você armazena dados pela primeira vez, portanto, não há necessidade de criar manualmente uma collection para usuários nesta etapa.
Agora estamos prontos para iniciar o servidor de desenvolvimento Grafbase usando a CLI:
1 npx grafbase dev
Este comando executa localmente toda a API Grafbase GraphQL que você pode usar ao desenvolver seu front-end. A API Grafbase se comunica diretamente com a Atlas Data API.
Quando o comando estiver em execução, você poderá acessar http://127.0.0.1:4000 e confira a GraphQL API.
Vamos testar a criação de usuários dentro de nossa MongoDB collection usando a mutação
userCreate
gerada que nos foi fornecida pelo Grafbase.1 mutation { 2 mongo { 3 userCreate(input: { 4 name: "Jamie Barton", 5 email: "jamie@grafbase.com", 6 age: 40 7 }) { 8 insertedId 9 } 10 } 11 }
Se tudo estiver conectado corretamente, você verá uma resposta parecida com esta:
1 { 2 "data": { 3 "mongo": { 4 "userCreate": { 5 "insertedId": "65154a3d4ddec953105be188" 6 } 7 } 8 } 9 }
Você deve repetir esta etapa algumas vezes para criar vários usuários.
Agora que criamos alguns usuários em nossa MongoDB collection, vamos tentar atualizar um usuário por
insertedId
:1 mutation { 2 mongo { 3 userUpdate(by: { 4 id: "65154a3d4ddec953105be188" 5 }, input: { 6 age: { 7 set: 35 8 } 9 }) { 10 modifiedCount 11 } 12 } 13 }
Usando a mutação
userUpdate
acima, set
um novo valorage
para o usuário em que o id
corresponde ao do ObjectID que passamos.Se tudo tiver sido bem-sucedido, você deverá ver algo como isto:
1 { 2 "data": { 3 "mongo": { 4 "userUpdate": { 5 "modifiedCount": 1 6 } 7 } 8 } 9 }
A exclusão de usuários é semelhante às mutações de criação e atualização acima, mas não precisamos fornecer dados adicionais
input
porque estamos excluindo apenas:1 mutation { 2 mongo { 3 userDelete(by: { 4 id: "65154a3d4ddec953105be188" 5 }) { 6 deletedCount 7 } 8 } 9 }
Se tudo tiver sido bem-sucedido, você deverá ver algo como isto:
1 { 2 "data": { 3 "mongo": { 4 "userDelete": { 5 "deletedCount": 1 6 } 7 } 8 } 9 }
O Grafbase gera a query
userCollection
que você pode usar para buscar todos os usuários. O Grafbase requer um valor de paginaçãofirst
ou last
com um valor máximo de 100
:1 query { 2 mongo { 3 userCollection(first: 100) { 4 edges { 5 node { 6 id 7 name 8 email 9 age 10 } 11 } 12 } 13 } 14 }
Aqui estamos buscando os usuários
first
100 da coleção. Você também pode passar um argumento de filtro e pedido para ajustar os resultados:1 query { 2 mongo { 3 userCollection(first: 100, filter: { 4 age: { 5 gt: 30 6 } 7 }, orderBy: { 8 age: ASC 9 }) { 10 edges { 11 node { 12 id 13 name 14 email 15 age 16 } 17 } 18 } 19 } 20 }
Usando a mesma API GraphQL, podemos buscar um usuário pelo ID do objeto. O Grafbase gera automaticamente a query
user
onde podemos passar o id
para o tipo de entradaby
:1 query { 2 mongo { 3 user( 4 by: { 5 id: "64ee1cfbb315482287acea78" 6 } 7 ) { 8 id 9 name 10 email 11 age 12 } 13 } 14 }
Cada solicitação que fizemos até agora à nossa GraphQL faz uma viagem de ida e volta ao MongoDB database. Isso é bom, mas podemos melhorar ainda mais os tempos de resposta ativando o Cache de borda para GraphQL queries.
Para ativar o GraphQL Edge Caching, dentro de
grafbase/grafbase.config.ts
, adicione o seguinte à exportaçãoconfig
:1 export default config({ 2 schema: g, 3 cache: { 4 rules: [ 5 { 6 types: 'Query', 7 maxAge: 60 8 } 9 ] 10 } 11 })
Esta configuração armazenará em cache qualquer query. Se você quiser desabilitar o cache em algumas collections, também pode fazer isso. Saiba mais sobre o Cache para o GraphQL Edge.
Até agora, estamos trabalhando com o Grafbase localmente usando a CLI, mas agora é hora de implementar isso em todo o mundo com o GitHub.
Se você já tem um repositório Github existente, vá em frente e confirme as alterações que fizemos até agora. Se você ainda não tiver um repositório do GitHub, precisará criar um, confirmar este código e enviá-lo para o GitHub.
Agora, crie um novo projeto com o Grafbase e conecte sua conta do GitHub. Você precisará permitir que o Grafbase leia o conteúdo do seu repositório, portanto, certifique-se de selecionar o repositório correto e permitir isso.
Antes de clicar em Implantar, certifique-se de inserir as variáveis de ambiente obtidas anteriormente no tutorial. O Grafbase também oferece suporte a variáveis de ambiente para ambientes de visualização, portanto, se você quiser usar um MongoDB database diferente para qualquer implantação de visualização do Grafbase, poderá configurá-lo posteriormente.
Agora, clique em Implementar e você será direcionado ao painel do seu projeto, onde poderá recuperar o ponto de conexão daAPI e a chavede API. É isso ai! Você tem uma API GraphQL implantada na borda que é totalmente gerenciada pelo Grafbase.
Como o Grafbase gera uma API CRUD para seu MongoDB database e o expõe por HTTP, vale a pena falar sobre segurança por um momento.
O Grafbase exige que você, por padrão, passe um cabeçalho
x-api-key
com solicitações. É recomendável fazer solicitações ao Grafbase apenas do lado do servidor, e não do cliente com essa chave de API.A exposição deste cabeçalhox-api-key
no cliente deve ser evitada para evitar ataques maliciosos indesejados.Todas as solicitações que fizemos até agora foram dentro do Pathfinder, que aplica esse cabeçalho a todas as solicitações por padrão. Abaixo está um exemplo de solicitação cURL que mostra como você pode fazer essa solicitação fora do Pathfinder com o cabeçalho:
1 curl --request POST \ 2 --url http://api.cartql.com/ \ 3 --header 'Content-Type: application/json' \ 4 --header 'apiKey: YOUR_API_KEY' \ 5 --data '{"query":"query {\n\tmongo {\n\t\tuserCollection(\n\t\t\tfirst: 100\n\t\t\tfilter: { age: { gt: 30 } }\n\t\t\torderBy: { age: ASC }\n\t\t) {\n\t\t\tedges {\n\t\t\t\tnode {\n\t\t\t\t\tid\n\t\t\t\t\tname\n\t\t\t\t\temail\n\t\t\t\t\tage\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n"}'
Você pode obter a chave de API de produção do seu projeto nas Configurações do projeto do Grafbase.
Neste tutorial, mostramos a criação automática de uma GraphQL API para collection em nosso MongoDB database. Também cobrimos a redução de viagens ao MongoDB database configurando o GraphQL Edge Cache para que, onde quer que seus usuários estejam, eles terão respostas super rápidas.
Você pode continuar sua maneira de usar o GraphQL aprendendo como integrar a API do GraphQL que criamos neste tutorial em seu aplicativo web ou móvel existente usando um cliente do GraphQL. Alguns clientes populares incluem Apollo Client, URQLe Houdini.
Se você tiver dúvidas ou comentários, continue a conversa na Comunidade de Desenvolvedores do MongoDB.