Como Implementar o Padrão BFF com Route Handlers do Next.js Antes da API PHP

O Desafio de Conectar Telas Modernas a Sistemas Legados

Quando construímos aplicações web modernas, frequentemente nos deparamos com uma desconfortável realidade arquitetural. De um lado, temos interfaces reativas construídas em frameworks como React e Next.js, que exigem dados limpos, estruturados sob medida e prontos para renderização instantânea. Do outro, pilhas tecnológicas consolidadas, como APIs legadas em PHP, que entregam estruturas complexas, repletas de campos desnecessários e acopladas a regras de banco de dados legadas. Na prática, isso significa que o navegador do usuário acaba processando muito mais informação do que o necessário apenas para exibir uma lista simples na tela.

Para resolver esse atrito, a engenharia de software recorre ao padrão BFF, abreviação para Backend for Frontend. Trata-se de uma camada intermediária de software cuja única responsabilidade é servir de tradutoreco e alfândega entre o cliente web e os servidores de backend. Em vez de fazer com que a aplicação React converse diretamente com a API PHP, nós inserimos um servidor dedicado que consome os dados brutos do PHP, filtra o que importa, reorganiza o formato e entrega tudo mastigado para a interface. Essa estratégia isola a complexidade do passado e acelera a entrega de valor no presente.

O Papel dos Route Handlers no Ecossistema Next.js

Dentro do framework Next.js, a implementação de um BFF tornou-se incrivelmente fluida graças aos Route Handlers. Um Route Handler é, na essência, uma função JavaScript ou TypeScript executada no servidor que responde a requisições HTTP tradicionais, como GET, POST, PUT e DELETE. Na prática, eles substituem as antigas rotas de API tradicionais e rodam no mesmo ambiente Node.js ou Edge da sua aplicação, permitindo acesso seguro a variáveis de ambiente sensíveis, cache agressivo e manipulação direta de cabeçalhos de rede.

Utilizar Route Handlers como BFF significa que você pode centralizar chamadas de autenticação, mascarar chaves de API secretas e executar agregações de dados sem expor a infraestrutura PHP diretamente ao cliente. Quando o usuário clica em um botão na interface, o navegador faz uma requisição limpa para a própria rota do Next.js. O Route Handler intercepta esse pedido, dispara requisições paralelas para o backend PHP, processa as respostas e devolve ao front-end apenas o JSON estritamente necessário para desenhar a tela.

Arquitetura Prática do Fluxo de Dados

Para visualizar essa operação na prática, imagine um cenário onde um painel de controle precisa exibir o perfil do usuário logado junto com suas transações recentes. Em uma arquitetura tradicional, o front-end faria duas requisições separadas para a API PHP ou receberia um monstro de objeto JSON com cem propriedades irrelevantes. Com o BFF em Next.js, a rota intermediária assume o trabalho pesado de orquestração.

Abaixo está um exemplo funcional de um Route Handler em Next.js que atua como BFF, consumindo dados de uma API PHP externa, tratando o payload e entregando o resultado formatado:

import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  try {
    const phpApiResponse = await fetch('https://api.meulegado.com/v1/user-data', {
      headers: {
        'Authorization': `Bearer ${process.env.PHP_API_SECRET_TOKEN}`,
        'Content-Type': 'application/json',
      },
    });

    if (!phpApiResponse.ok) {
      return NextResponse.json({ error: 'Falha ao buscar dados no PHP' }, { status: 502 });
    }

    const rawData = await phpApiResponse.json();

    const optimizedPayload = {
      userName: rawData.user_full_name,
      activeStatus: rawData.status === 1,
      recentTransactions: rawData.transactions.slice(0, 5).map((tx: any) => ({
        id: tx.tx_id,
        amountFormatted: `R$ ${tx.value}`,
      })),
    };

    return NextResponse.json(optimizedPayload);
  } catch (error) {
    return NextResponse.json({ error: 'Erro interno no BFF' }, { status: 500 });
  }
}

Tratamento de Erros, Segurança e Otimização de Cache

Implementar uma camada intermediária não serve apenas para embelezar JSONs; é também uma excelente estratégia de segurança e resiliência operacional. Como a API PHP fica escondida atrás do Next.js, ela deixa de ser acessível publicamente por scripts maliciosos no navegador. Além disso, o BFF pode implementar políticas de cache inteligentes. Se dez usuários acessarem a mesma página de estatísticas simultaneamente, o Route Handler pode servir uma resposta cacheada por trinta segundos, poupando o servidor PHP de picos desnecessários de processamento.

Outro ponto crítico é o tratamento robusto de falhas. Se a API PHP cair ou responder com lentidão extrema, o BFF tem a oportunidade de agir com inteligência. Em vez de quebrar a interface do usuário com uma tela vermelha de erro catastrófico, o Route Handler pode retornar dados estáticos de fallback, um estado vazio controlado ou mensagens amigáveis, mantendo a experiência de navegação estável e protegendo o negócio contra indisponibilidades pontuais.

Considerações Finais sobre Arquiteturas Híbridas

Adotar o padrão BFF utilizando Route Handlers do Next.js em conjunto com sistemas legados em PHP representa uma ponte elegante entre o passado e o futuro da engenharia web. Essa abordagem permite que equipes continuem extraindo valor de bases de código PHP maduras e estáveis, enquanto oferecem aos usuários finais uma experiência de interface extremamente rápida, fluida e moderna. A chave para o sucesso reside em manter o BFF enxuto: sua função é orquestrar, traduzir e proteger, nunca acumular regras complexas de negócio que pertençam ao domínio principal da aplicação.