API Gateway no Node.js é uma camada de entrada que centraliza roteamento, autenticação, limites, observabilidade e políticas comuns antes que a requisição alcance serviços internos. Em arquiteturas com vários backends, o gateway reduz duplicação e oferece um ponto consistente para clientes web, mobile e integrações.
O gateway não deve concentrar toda a lógica de negócio. Seu papel principal é proteger e organizar a borda do sistema: validar identidade, escolher o destino, aplicar políticas e devolver uma resposta previsível.
Quando usar um API Gateway
- vários serviços atendem o mesmo produto;
- clientes precisam de uma URL única;
- autenticação e rate limiting devem ser centralizados;
- é necessário versionar rotas e migrar serviços gradualmente;
- métricas e logs precisam de contexto comum.
Gateway mínimo com Node.js
import http from 'node:http';
import { request } from 'undici';
const routes = {
'/users': 'http://users:3001',
'/orders': 'http://orders:3002'
};
const server = http.createServer(async (req, res) => {
const prefix = Object.keys(routes).find((key) => req.url.startsWith(key));
if (!prefix) {
res.writeHead(404).end('Not found');
return;
}
const target = routes[prefix];
const response = await request(`${target}${req.url}`, {
method: req.method,
headers: req.headers,
body: ['GET', 'HEAD'].includes(req.method) ? undefined : req
});
res.writeHead(response.statusCode, response.headers);
response.body.pipe(res);
});
server.listen(8080);Esse exemplo mostra apenas o fluxo básico. Em produção, adicione timeouts, cancelamento, limites de corpo, retries seletivos e proteção contra destinos arbitrários. Veja Undici no Node.js e Retry com Backoff no Node.js.
Roteamento explícito
Mantenha uma tabela controlada de destinos. Nunca aceite uma URL de backend enviada pelo cliente, pois isso transforma o gateway em vetor de SSRF. Rotas podem ser definidas por prefixo, host, versão ou cabeçalho interno validado.
Autenticação e autorização
O gateway pode validar assinatura de JWT, expiração, issuer e audience. Depois, encaminha apenas claims necessárias em headers internos assinados ou em contexto de rede confiável. A autorização de negócio, como “pode cancelar este pedido?”, continua no serviço responsável.
Consulte JWT no Node.js, RBAC no Node.js e ABAC no Node.js.
Timeouts e cancelamento
Defina um prazo total para a requisição e distribua o orçamento entre as chamadas internas. Um gateway sem timeout pode acumular conexões e amplificar uma falha downstream.
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 2_000);
try {
const response = await fetch(url, { signal: controller.signal });
return response;
} finally {
clearTimeout(timer);
}Rate limiting
Aplique limites por tenant, usuário, API key e rota. Retorne 429 Too Many Requests com Retry-After quando apropriado. Para ambientes distribuídos, o contador precisa de armazenamento compartilhado ou algoritmo compatível com múltiplas instâncias.
Transformação de respostas
Transformações simples podem adaptar nomes de headers ou remover campos internos. Evite converter grandes payloads inteiros na memória. Prefira streaming e mantenha contratos claros para não criar acoplamento oculto.
Agregação de APIs
Um gateway pode combinar respostas de dois serviços, mas isso aumenta latência e dependências. Execute chamadas independentes em paralelo, imponha timeout individual e defina comportamento quando uma fonte falhar.
const [profile, plan] = await Promise.allSettled([
fetchProfile(userId),
fetchPlan(userId)
]);Headers importantes
traceparentpara rastreamento distribuído;x-request-idou identificador equivalente;forwardedoux-forwarded-*somente de proxies confiáveis;- remoção de headers hop-by-hop;
- limites para quantidade e tamanho de headers.
Retries seguros
Não repita qualquer requisição automaticamente. GET e operações idempotentes são candidatas melhores. Para POST, use Idempotency Keys quando o domínio permitir. Retries devem respeitar deadline, jitter e respostas como Retry-After.
Circuit breaker e bulkhead
Um circuit breaker evita insistir em um serviço indisponível. Bulkheads separam recursos por destino para impedir que um backend lento consuma toda a capacidade do gateway. Consulte Circuit Breaker no Node.js.
Observabilidade
Registre método, rota normalizada, status, duração, serviço de destino, tentativas e erro. Não use URL completa como label de métrica, pois IDs geram cardinalidade alta. Propague contexto de trace e associe logs ao mesmo identificador.
Segurança operacional
- limite tamanho de body e tempo de upload;
- valide Content-Type;
- remova headers internos vindos da internet;
- use TLS entre componentes quando necessário;
- mantenha allowlist de destinos;
- não exponha mensagens internas de erro;
- proteja endpoints administrativos.
Graceful shutdown
Ao receber sinal de encerramento, pare de aceitar novas conexões, aguarde requisições em andamento dentro de um prazo e feche pools. Isso evita respostas interrompidas durante deploys.
Erros comuns
- colocar regra de negócio no gateway;
- não definir timeout;
- confiar em headers enviados pelo cliente;
- repetir POST sem idempotência;
- carregar respostas grandes em memória;
- usar uma única fila de conexões para todos os serviços;
- registrar tokens e dados sensíveis.
Conclusão
API Gateway no Node.js organiza a borda de sistemas distribuídos e aplica políticas comuns sem duplicação. O desenho mais seguro mantém roteamento explícito, timeouts curtos, autenticação consistente, observabilidade e isolamento por serviço.
Comece pequeno, meça a necessidade de agregação e evite transformar o gateway em um monólito oculto. Consulte a documentação HTTP do Node.js e a documentação oficial do Undici.
