Pular para o conteúdo
Sistemas próprios. Conhecimento aplicado.
Agência A2CRConte seu projeto
Sistemas

GraphQL e BFF: como montar uma camada de dados para portais empresariais

Planeje a composição de dados de um portal com contratos claros, autorização por campo, limites de consulta e respostas compreensíveis quando uma fonte falha.

GraphQL e BFF: como montar uma camada de dados para portais empresariais

Um portal pode reunir pedidos, documentos, posição financeira e chamados sem que essas informações pertençam ao mesmo sistema. Para o cliente, existe uma única página. Para a equipe técnica, existem identidades diferentes, permissões, tempos de atualização e fontes que podem falhar separadamente. A camada que monta essa experiência precisa preservar essas diferenças em vez de apenas esconder várias chamadas atrás de um endereço.

GraphQL e BFF são opções para enfrentar esse problema, mas não representam a mesma decisão. Este guia propõe um método de planejamento para gestores e equipes de desenvolvimento compararem os caminhos. Os exemplos e números são hipotéticos, elaborados para explicar o raciocínio, e não resultados de um cliente da A2CR.

1. Comece pela tarefa que a página precisa permitir

Desenhe a tarefa antes da consulta. Um comprador que deseja acompanhar um pedido precisa reconhecer o item, entender sua situação e saber qual ação está disponível. Ele talvez não precise do histórico financeiro completo ou dos dados internos do vendedor. Expor tudo porque a API permite tende a tornar a interface lenta e o contrato confuso.

Registre, para cada bloco da página, a origem da informação, o responsável por sua qualidade e a decisão que ela sustenta. A data prevista de entrega pode vir do ERP, enquanto a posição do transporte vem de outro fornecedor. Se uma dessas fontes estiver atrasada, o portal deve comunicar a diferença. Um horário único no rodapé não explica qual dado está atualizado.

2. Separe GraphQL de uma camada BFF

GraphQL utiliza um schema para definir os dados e permite que a consulta declare os campos desejados. A documentação de fundamentos do GraphQL apresenta essas operações e sua execução. Isso descreve uma forma de interagir com a API, não uma obrigação de adotar um banco específico.

BFF significa backend orientado a uma interface. A referência de arquitetura da Microsoft descreve uma camada entre frontend e serviços de origem, ajustada às necessidades daquela experiência. Um BFF pode expor REST ou GraphQL. Também é possível utilizar GraphQL sem criar um serviço diferente para cada canal.

A pergunta prática é dupla: qual contrato atende a interface e quem ficará responsável por compor a resposta? Tratar essas perguntas separadamente evita escolher uma tecnologia antes de delimitar sua responsabilidade.

3. Defina o que a composição pode decidir

A camada de composição pode reunir dados, adaptar nomes e organizar uma resposta. Ela não deve se tornar, por acidente, a proprietária de todas as regras comerciais. Aprovar um desconto, reservar estoque e cancelar uma cobrança têm efeitos que precisam continuar sob autoridade explícita.

Uma convenção útil é manter os comandos relevantes no serviço que controla a capacidade de negócio. O portal solicita a operação e recebe seu resultado identificável. Para leitura, o BFF pode preparar uma visão adequada à tela. Se a adaptação começar a decidir condições contratuais diferentes das adotadas pelo ERP, existe uma divergência de regra a resolver, não um detalhe de interface.

4. Compare alternativas com o mesmo cenário

AlternativaBoa pergunta de avaliaçãoCusto que precisa aparecerEvidência do piloto
Interface consulta serviços diretamenteAs fontes já têm contratos adequados ao usuário?Várias dependências no navegadorJornada completa com fonte indisponível
BFF com operações REST específicasAs telas possuem necessidades estáveis?Manter operações por experiênciaResposta suficiente sem consultas extras
GraphQL em camada compartilhadaVários consumidores precisam de seleções diferentes?Governança do schema e custo das consultasConsultas representativas e limites aplicados
GraphQL em um BFFA interface exige composição e seleção flexível?Duas escolhas arquiteturais para operarResponsabilidades separadas e documentadas

A tabela é um instrumento de comparação, não uma classificação universal. A solução com menos componentes pode ser a melhor quando o problema é pequeno e os contratos existentes já atendem à jornada.

5. Caso didático: a página de pedidos da Atlas Peças

A empresa fictícia Atlas Peças quer mostrar os 20 pedidos mais recentes de cada comprador. O ERP fornece pedidos; o serviço logístico fornece entregas; o atendimento informa solicitações abertas. O protótipo consulta a logística individualmente para cada pedido e faz mais uma chamada para o atendimento.

No cenário inicial hipotético, uma abertura pode provocar uma consulta ao ERP, 20 à logística e uma ao atendimento: 22 chamadas externas. Isso não demonstra lentidão por si só, pois concorrência, cache e tempos de resposta importam. Demonstra, entretanto, uma dependência que precisa ser medida.

A equipe primeiro verifica se a logística oferece consulta em lote. Se houver, o desenho pode usar três chamadas externas por abertura. Se não houver, define agrupamento, limite de concorrência e reaproveitamento controlado. A redução de chamadas é uma hipótese de arquitetura a testar, não um resultado comercial presumido.

6. Faça o custo das consultas aparecer

Uma consulta curta pode solicitar uma árvore extensa: clientes, pedidos, itens e documentos de cada item. A aparência simples do pedido não representa o trabalho necessário para respondê-lo. Por isso, defina paginação e limites de quantidade antes de aceitar consultas livres no ambiente produtivo.

Na Atlas, o piloto limita a primeira página a 20 pedidos e exige cursor para continuar. Uma consulta que solicite milhares de itens deve ser recusada de maneira compreensível. A equipe também registra o número de acessos às fontes por operação. Essa observação ajuda a reconhecer o problema conhecido como N+1: uma consulta inicial seguida por outra para cada resultado.

Não copie limites de outro projeto sem ensaio. O orçamento de uma operação deve considerar as fontes acionadas, os tamanhos das listas e o custo de transformação. O limite existe para proteger uma capacidade observada, não para produzir um número bonito na documentação.

7. Autorize a informação no alcance correto

Receber um identificador de cliente na consulta não significa que o usuário pode consultar aquele cliente. A identidade autenticada precisa ser vinculada à organização e ao alcance permitido. O mesmo cuidado vale para campos que apenas gestores podem enxergar, como margem ou observações internas.

Monte testes com duas empresas fictícias e usuários com papéis diferentes. Troque um identificador válido pelo de outra organização. Solicite diretamente um campo que a interface não mostra. Consulte uma lista e depois um objeto individual. A proteção deve funcionar em todos esses percursos, inclusive quando a resposta vem de cache.

Em revisões de segurança, prefira demonstrar o bloqueio pela API. Esconder um botão no navegador não constitui evidência de que a informação deixou de estar acessível.

8. Planeje respostas incompletas sem inventar estados

Na página de pedidos, uma falha da transportadora pode impedir a atualização da entrega sem impedir a leitura do pedido. O produto deve decidir quais blocos podem aparecer parcialmente e quais dependem de confirmação completa. Essa decisão deve ser observável no contrato e no texto da tela.

Um retorno ausente não deve ser convertido em “sem entregas” ou “nenhum chamado aberto”. São afirmações distintas. Use estados como informação indisponível, atualização pendente e ausência confirmada. Mostre uma ação de recuperação quando ela fizer sentido, sem obrigar o usuário a repetir uma operação com efeitos.

Para uma ação crítica, como cancelar pedido, o portal precisa apresentar o resultado confirmado pelo serviço responsável. A resposta de leitura parcial não autoriza o frontend a presumir que o cancelamento aconteceu.

9. Cache exige identidade, validade e finalidade

Antes de armazenar uma resposta composta, descreva quais partes podem ser reutilizadas e por quanto tempo. Um nome de produto pode tolerar atualização menos frequente que uma reserva de estoque. Colocar ambos no mesmo cache sem critério cria um compromisso oculto de atualização.

Defina a chave com os elementos que realmente mudam a resposta: organização, usuário ou papel quando aplicável, filtros e contexto de autorização. Depois ensaie troca de sessão e mudança de permissões. A tela não pode reutilizar informação privada de um atendimento anterior.

Na Atlas, a equipe escolhe uma política provisória para cada bloco e a revê com a operação. Essa política faz parte do aceite da página. Não basta demonstrar uma segunda abertura rápida se ninguém consegue explicar por que o dado ainda é confiável.

10. Quando outra arquitetura é suficiente

Um portal com duas telas e um único serviço pode não justificar uma camada adicional. Se o contrato já devolve os dados necessários com autorização e tempo adequados, introduzir GraphQL pode aumentar o trabalho de operação sem resolver uma dificuldade relevante.

Também evite um BFF por dispositivo quando as diferenças entre as interfaces forem pequenas. Compartilhar uma capacidade bem definida costuma ser preferível a manter cópias de regras que se afastam com o tempo. A decisão deve considerar a frequência de mudança, o número de consumidores e a capacidade da equipe de manter o contrato.

11. Escreva critérios de aceite que possam falhar

Para o piloto da Atlas, uma proposta de aceite inclui: a lista respeita o limite de 20 pedidos; a navegação por cursor não omite pedidos no conjunto estável de teste; uma organização não acessa pedidos de outra; a indisponibilidade logística não aparece como ausência de entrega; e cada ação mantém uma referência consultável.

Acrescente critérios de desempenho a partir de uma medição definida. Informe ambiente, volume, concorrência e cenário. Uma meta sem essas condições permite aprovar uma consulta vazia e descobrir o problema quando a lista possui documentos e itens reais.

O aceite também precisa incluir a atualização do schema e um consumidor anterior. Uma mudança que atende a nova tela, mas quebra uma integração existente, não deve ser considerada uma melhoria concluída.

12. Oficina: monte o contrato de uma página

Escolha uma página do seu portal e desenhe cinco campos: bloco da tela, pergunta respondida, fonte, alcance permitido e comportamento quando a fonte falha. Em seguida, descreva duas alternativas de composição e indique qual componente seria responsável por cada adaptação.

Use um conjunto pequeno: dois clientes fictícios, três usuários e 25 pedidos. A quantidade permite testar uma segunda página sem exigir uma base extensa. Inclua um pedido com informação ausente e outro que tenha sido alterado depois da primeira leitura. Execute a jornada com cada papel e registre os resultados.

Ao terminar, apresente a decisão em uma página. Diga o que foi escolhido, qual problema ela resolve e que custo novo será assumido. Se a equipe não consegue explicar essa escolha sem mencionar popularidade da tecnologia, ainda falta relacionar o desenho à operação.

Checklist para revisar a composição

  • A tarefa do usuário está descrita antes dos campos da API.
  • Cada bloco identifica fonte e responsável pela qualidade.
  • GraphQL e BFF foram avaliados como decisões diferentes.
  • Listas possuem limites e paginação verificáveis.
  • O número de acessos às fontes pode ser observado.
  • A autorização foi testada entre duas organizações.
  • Campos privados são protegidos no servidor.
  • Respostas ausentes não viram estados comerciais inventados.
  • O cache respeita identidade, alcance e validade.
  • Uma versão anterior do consumidor participa do teste.

Perguntas frequentes

GraphQL substitui o ERP ou o banco de dados?

Não. Ele define uma interface de consulta e operação. Os dados e as regras continuam precisando de proprietários, armazenamento adequado e controles implementados nos componentes responsáveis.

Um BFF precisa utilizar GraphQL?

Não. Um BFF pode expor operações REST ajustadas à interface. A escolha depende da necessidade de composição, dos consumidores e do custo de manter o contrato.

Uma única chamada do navegador garante desempenho melhor?

Não. Essa chamada pode provocar muitas operações internas. Meça o percurso completo, as fontes acionadas e o volume retornado antes de concluir que a página melhorou.

Aprofunde a decisão do portal

Para organizar o contrato das operações, consulte API-first com OpenAPI. Para relacionar acesso e tarefas do cliente, veja o planejamento de um portal B2B.

Se o seu portal reúne fontes diferentes e a equipe precisa avaliar essa composição, a A2CR pode conversar sobre o contexto de desenvolvimento de sistemas personalizados. Leve uma página concreta, suas fontes e as dificuldades observadas para orientar a avaliação.

Modelo para aplicar na sua empresa

Baixar o checklist de GraphQL e BFF para portais empresariais. Use-o para registrar evidências, responsáveis e pendências da avaliação.

Fontes consultadas

Revisão documental: 18/11/2026. Cenários e números didáticos não representam resultados medidos de clientes. A aplicação exige conferir a documentação e as condições do projeto.

Compartilhar