Agora que já entendemos, de maneira fundamental, as diferenças entre uma API RESTful e o GraphQL, além de como esses conceitos se integram no desenvolvimento de um back-end específico para um front-end, é o momento de explorarmos a implementação do lado do servidor. Precisamos analisar quais tecnologias serão utilizadas para construir um servidor GraphQL eficaz.
Entendendo a implementação do servidor GraphQL
Utilizaremos duas tecnologias que funcionam bem juntas: o Nest, um framework back-end, que será familiar para quem vem do ecossistema Angular, pois é modular e lembra a implementação de componentes antes dos componentes independentes do Angular. Isto é, é um framework para nosso back-end.
E o Apollo, que é a camada do GraphQL, responsável por entregar o serviço. Implementamos os serviços utilizando o Apollo, e escrevemos o código e o Nest. O Apollo cuida de tudo o que é necessário para o GraphQL funcionar.
O papel central do schema no GraphQL
Falando sobre GraphQL, é fundamental compreender o que é o schema.
O schema é uma documentação de baixo nível que facilita a comunicação entre a linguagem do GraphQL e a linguagem que estamos utilizando. Embora possamos ler o schema diretamente no arquivo, o mais importante é entender que o papel do schema é definir todas as operações que podem ser realizadas dentro do nosso servidor GraphQL.
Definimos os nossos modelos, o que enviamos, o que podemos solicitar, a possibilidade de aplicar filtros, o formato dos dados (tipos) e até mesmo o suporte a real-time por meio da camada de subscriptions do GraphQL.
O schema desempenha um papel central no GraphQL, pois documenta de forma clara o que pode ser realizado e o que é transmitido entre os diferentes pontos da comunicação.
No cenário em que desejamos solicitar playlists e vídeos de um canal, é no schema que fica definida aquilo que podemos pedir e o que cada campo representa.
Code-first ou schema-first?
Ao criarmos um servidor GraphQL, devemos escolher entre duas abordagens para a definição do schema:
Code-first
- Definimos os modelos no código
- Geração de automática dos tipos
Code -> Schema -> Client
Podemos gerar o schema a partir do código, utilizando frameworks como Nest ou Apollo (o schema é um arquivo com todas essas informações), ou criar o schema de forma antecipada e, em seguida, desenvolver o código com base nele. Cada cenário possui suas próprias vantagens e desvantagens.
Ao desenvolvermos um BFF (back-end for front-end), podemos focar na escrita do código, na definição dos nossos modelos, em como eles irão trafegar e na estruturação lógica da hierarquia de informações entre os modelos.
Ao terminarmos de codar, o GraphQL, juntamente com o Nest ou Apollo, gera o schema automaticamente. Esse processo assegura que o código fonte seja a única fonte de verdade.
Schema-first
Se optarmos por criar o schema primeiro, nossa intenção provavelmente será ser agnósticos em relação à tecnologia, ou seja, sem nos preocuparmos com a linguagem de programação utilizada, e sim focando principalmente na documentação. Essa abordagem é especialmente útil em cenários com múltiplas equipes e domínios de informação distintos, onde pode ser vantajoso estabelecer um schema bem definido antes de iniciar o desenvolvimento.
Essa estratégia pode até facilitar o processo de desenvolvimento, pois ao entregar o schema para uma equipe de front-end, é possível que o back-end e o front-end sejam desenvolvidos em paralelo, com um contrato já estabelecido entre as partes.
- Esquema em SDL
- Agnóstico de linguagem
Usaremos code-first para aproveitar o TypeScript e o Nest.js
Entendendo nosso cenário
No nosso cenário, em que estamos construindo um BFF para o front-end, podemos optar pela abordagem Code-First. Nesse caso, focamos no desenvolvimento do código e delegamos a geração do schema para o Nest e Apollo. A partir daí, começamos a implementar os resolvers.
No schema da seção "O papel central do schema no GraphQL", temos a camada de query, que define as consultas disponíveis. O que define cada consulta e o que pode ser solicitado em cada uma delas, é o resolver.
O resolver, por sua vez, é uma função que pode receber argumentos para aplicar filtros aos recursos. Por exemplo, no caso de channels, podemos escolher se incluímos o username como argumento. Se o username for fornecido, o filtro é aplicado, trazendo apenas os canais correspondentes; caso contrário, todos os canais são retornados. Em suma, o resolver é uma função.
Um ponto importante do GraphQL mais próximo da implementação está no resolver buscar os dados, independentemente de sua origem (banco de dados, arquivo JSON ou de configuração), encapsulando o processo de obtenção dessas informações na função.
O que são resolvers no GraphQL
Ao implementar essa funcionalidade no Nest utilizando o Apollo, definimos um objeto, que no exemplo é de categoria, que inclui campos como id, displayName e ícone:
@ObjectType()
export class Category {
@Field(() => ID)
id: string;
@Field()
displayName: string;
@Field()
icon: string;
}
Iniciamos definindo o modelo, sendo que desejamos entregar uma categoria.
Na implementação do resolver, informamos ao Next e ao Apollo que a classe se trata de um resolver de categoria. A partir dessa definição, ela será responsável por fornecer as informações relacionadas a esse tipo específico de dado. Esse conhecimento deve ser utilizado durante a geração do schema, para que possamos identificar corretamente as ações necessárias e os tipos possíveis para os campos de uma categoria.
Analisaremos o exemplo:
@Resolver(() => Category)
export class CategoryResolver {
@Query(() => [Category])
async categories(): Promise<Category[]> {
return [
{
id: 'camisetas',
displayName: 'Camisetas',
icon: 'https://raw.content.com/icon.png',
},
];
}
}
Criamos um resolver para categoria, o qual define uma query responsável por retornar uma lista de categorias. Com isso, retornamos a lista. No nosso exemplo, buscamos uma única categoria, no caso, a de camisetas, mas o processo é flexível, permitindo que a busca seja realizada a partir de qualquer fonte de dados necessária.
Para o nosso cenário específico, estabelecemos a conexão com o super base como a fonte de dados.
Verificando os possíveis cenários
Temos um resolver que retorna categorias, mas, no caso de um produto com categoria associada, por algum motivo, não queremos retornar a categoria completa. Em vez disso, desejamos encapsular essa informação e retornar apenas o que é relevante para a pessoa usuária, como o displayName.
Resolve Field
Conseguimos desenvolver essa lógica utilizando o resolve field:
@Resolver('Product')
export class ProductResolver {
@Query(() => [Product])
async getProducts(): Promise<Product[]> {
return [
{
name: 'Tênis Esportivo',
price: 199.99,
seller: 'Loja XYZ',
image: 'image-url',
category: { id: '1', displayName: 'Calçados' },
},
];
}
@ResolveField(() => String)
async categoryName(@Parent() product: Product): Promise<string> {
return product.category.displayName;
}
}
Podemos criar um resolve field para tratar campos específicos de um produto, retornando apenas as informações relevantes para a pessoa usuária ao solicitar a categoria de um produto, como, por exemplo, o nome (displayName).
Ao seguir esses três passos, implementamos resolvers dentro do ecossistema do NestJS utilizando o Apollo. No contexto do nosso modelo de negócio, trabalhamos com o resolver, e, quando necessário, podemos incluir resolvers específicos para campos ("resolver fields").
Ao implementarmos utilizando o Next e o Apollo como servidor GraphQL, fazemos isso utilizando anotações como @Resolver e @Object. O Apollo nos oferece uma interface de playground, que funciona como uma documentação interativa, similar ao Swagger em APIs RESTful. Esse playground permite que escrevamos consultas, selecione os campos desejados e testemos as respostas, facilitando o desenvolvimento e a compreensão do que está sendo enviado e retornado.
Com a implementação dos resolvers, conseguimos expandir e aprimorar nossa API GraphQL, que desenvolveremos para o front-end.
Lembre-se de que estamos criando um back-end sob medida, um BFF (back-end for front-end). Se surgir qualquer dúvida durante a implementação, podemos contar com o Discord, o fórum ou a colaboração da comunidade.
Próximo passo
Agora, é o momento de focarmos na construção da camada do servidor, pois o próximo passo será conectar o front-end ao servidor. Nos encontramos na próxima aula!