Node.js come BFF (Backend for Frontend): pattern architetturale per applicazioni composite

A novembre 2024 un cliente del settore e-commerce B2B mi ha mostrato il pannello di rete del browser durante il caricamento della dashboard principale del suo portale: 43 richieste HTTP verso 5 API diverse, con un tempo di caricamento totale di 7,2 secondi. Il portale era un frontend Vue.js che consumava direttamente le API di cinque sistemi backend: l'API del gestionale ordini (Laravel), l'API del catalogo prodotti (un servizio legacy in PHP procedurale), l'API del magazzino (SOAP wrapped in REST), l'API del corriere per il tracking (REST di un provider esterno), e l'API del sistema di fatturazione. Ogni sistema aveva il proprio formato di risposta, i propri tempi di risposta (dai 50 ms dell'API Laravel ai 1.200 ms del wrapper SOAP), e i propri meccanismi di autenticazione. Il frontend doveva orchestrare 43 chiamate, gestire 5 formati diversi di errore, e aspettare che la più lenta delle 5 API rispondesse prima di poter renderizzare la dashboard.

La soluzione non era riscrivere le cinque API backend (funzionavano correttamente, non avevano bisogno di essere toccate) né aggiungere logica di aggregazione nel frontend (che era già troppo complesso). La soluzione era un Backend for Frontend (BFF) - un layer intermedio scritto in Node.js e TypeScript che si posiziona tra il frontend e le API backend, aggrega le risposte di più API in un singolo endpoint ottimizzato per le esigenze del frontend, trasforma i dati nel formato esatto che il componente Vue si aspetta, e implementa caching intelligente per evitare di chiamare API lente ad ogni richiesta. Dopo l'introduzione del BFF, la dashboard si carica con una sola richiesta HTTP in 800 millisecondi - un miglioramento dell'89% nel tempo di caricamento percepito dall'utente, senza toccare una riga di codice nei backend esistenti.

Cos'è il pattern BFF e quando ha senso introdurlo?

Il Backend for Frontend è un pattern architetturale in cui crei un server backend dedicato a uno specifico frontend (web, mobile, o desktop) che fa da intermediario tra il client e i servizi backend reali. Non è un API gateway generico - è un server costruito per quel frontend specifico, che espone endpoint progettati esattamente per le esigenze delle schermate che il frontend deve renderizzare. La differenza è cruciale: un API gateway inoltra le richieste ai servizi backend e opzionalmente le aggrega; un BFF conosce il frontend e costruisce risposte su misura per le sue schermate.

Il pattern ha senso quando almeno due di queste condizioni sono vere: il frontend consuma più di tre API backend diverse con formati di risposta eterogenei; il frontend deve aggregare dati da più fonti per renderizzare una singola schermata; le API backend hanno tempi di risposta molto diversi e il frontend è bloccato dalla più lenta; il frontend deve trasformare i dati ricevuti dalle API prima di poterli usare (ad esempio, convertire formati di data, normalizzare nomi di campo, calcolare campi derivati). Se nessuna di queste condizioni è vera - se hai un solo backend Laravel e un frontend Vue che consuma la sua API - un BFF è over-engineering. Se tre o quattro sono vere contemporaneamente, come nel caso del cliente B2B, il BFF è la soluzione che produce il miglioramento più visibile con il minimo impatto sulle architetture esistenti.

Nel mio profilo professionale trovi il dettaglio dell'esperienza multi-stack che porto in queste architetture - la scelta di Node.js per il BFF non è casuale ma strategica, perché il modello event-driven di Node eccelle nell'aggregazione di chiamate I/O concorrenti, che è esattamente ciò che un BFF fa.

Perché Node.js e non PHP per il BFF?

La domanda è legittima: se il team ha competenze PHP, perché introdurre un runtime diverso? La risposta è tecnica e misurabile. Un BFF che aggrega 5 API diverse deve fare 5 chiamate HTTP concorrenti e aspettare che tutte rispondano prima di comporre la risposta. In PHP con FPM (modello process-per-request), ogni richiesta al BFF occupa un worker che resta bloccato in attesa delle risposte delle 5 API - il worker non può fare altro mentre aspetta. Con 50 richieste simultanee al BFF, servono 50 worker PHP impegnati in attesa di I/O. In Node.js, il modello event-loop asincrono gestisce tutte e 5 le chiamate HTTP in parallelo su un singolo thread senza bloccare: le 50 richieste simultanee vengono gestite dallo stesso processo Node con un consumo di memoria una frazione di quello dei 50 worker PHP.

Il risultato pratico: il BFF Node.js del cliente gira su un VPS Hetzner CPX11 (2 vCPU, 2 GB RAM, 3,85 euro al mese) e gestisce 500 richieste al minuto con una latenza p95 di 150 ms - incluso il tempo di chiamata alle 5 API backend. Lo stesso carico con un BFF PHP/FPM richiederebbe un server significativamente più grande per il numero di worker necessari a gestire le connessioni concorrenti in attesa.

L'implementazione: aggregazione, trasformazione e caching

Il cuore del BFF è un endpoint che aggrega le risposte di più API in una singola risposta ottimizzata per il frontend. Ecco l'implementazione dell'endpoint dashboard:

// src/routes/dashboard.ts - BFF endpoint per la dashboard
import { Router, Request, Response } from 'express'
import { cache } from '../middleware/cache'

const router = Router()

// Endpoint aggregato: una sola chiamata per tutta la dashboard
router.get('/api/bff/dashboard', cache('dashboard', 30), async (req: Request, res: Response) => {
  const tenantId = req.headers['x-tenant-id'] as string

  // Chiamate parallele a tutte le API backend
  const [ordini, catalogo, magazzino, tracking, fatturazione] = await Promise.allSettled([
    fetchOrdiniRecenti(tenantId),
    fetchStatsCatalogo(tenantId),
    fetchGiacenzeCritiche(tenantId),
    fetchSpedizioniInCorso(tenantId),
    fetchFattureScadute(tenantId),
  ])

  // Componi la risposta aggregata per il frontend
  res.json({
    ordini_recenti: extractData(ordini, []),
    stats_catalogo: extractData(catalogo, { totale: 0, attivi: 0 }),
    giacenze_critiche: extractData(magazzino, []),
    spedizioni_in_corso: extractData(tracking, []),
    fatture_scadute: extractData(fatturazione, []),
    // Timestamp per il frontend: quando è stata generata questa snapshot
    generated_at: new Date().toISOString(),
    // Segnala quali API hanno risposto e quali hanno fallito
    api_status: {
      ordini: ordini.status,
      catalogo: catalogo.status,
      magazzino: magazzino.status,
      tracking: tracking.status,
      fatturazione: fatturazione.status,
    },
  })
})

// Helper: estrae il valore o restituisce il fallback
function extractData<T>(result: PromiseSettledResult<T>, fallback: T): T {
  return result.status === 'fulfilled' ? result.value : fallback
}

Tre scelte architetturali in questo codice meritano spiegazione. La prima è Promise.allSettled invece di Promise.all: con allSettled, se una delle 5 API fallisce (ad esempio il servizio di tracking è temporaneamente down), le altre 4 risposte vengono comunque restituite al frontend con un flag api_status che indica quale servizio è degradato. Con Promise.all, il fallimento di una sola API farebbe fallire l'intera richiesta - un comportamento inaccettabile per una dashboard che deve mostrare informazioni da fonti indipendenti.

La seconda scelta è il middleware cache('dashboard', 30) che implementa un caching in Redis con TTL di 30 secondi per tenant. La dashboard del portale B2B viene caricata in media 12 volte al minuto (6 utenti che la refreshano ogni 5-10 secondi): senza cache, il BFF farebbe 60 chiamate API al minuto verso 5 backend; con cache, ne fa 2 al minuto (una ogni 30 secondi) e serve le altre 58 dalla cache Redis in meno di 1 millisecondo.

La terza scelta è il campo api_status nella risposta: il frontend può mostrare un indicatore visivo per ogni widget della dashboard - un badge verde se l'API ha risposto, un badge giallo se i dati sono dalla cache perché l'API non ha risposto nell'ultimo aggiornamento. Questo livello di trasparenza verso l'utente è un pattern di resilienza che in un'architettura senza BFF sarebbe molto più complesso da implementare.

Trasformazione dei dati: normalizzare cinque formati diversi

Oltre all'aggregazione, il BFF ha un secondo ruolo fondamentale: la trasformazione dei dati. Le 5 API backend usano formati di risposta diversi - l'API Laravel restituisce camelCase, l'API SOAP restituisce PascalCase con abbreviazioni italiane, l'API del corriere restituisce snake_case in inglese, e il sistema di fatturazione restituisce un XML convertito in JSON con nesting arbitrario. Il frontend Vue non dovrebbe preoccuparsi di queste differenze: il BFF normalizza tutto in un formato unico, coerente e documentato.

La normalizzazione avviene nei service layer del BFF - un file per ogni API backend che contiene la logica di trasformazione. Quando l'API del magazzino restituisce { QtaDisp: "42,5", CodArt: "ABC-001", DescArt: "Valvola DN50" }, il service lo trasforma in { quantita_disponibile: 42.5, codice_articolo: "ABC-001", descrizione: "Valvola DN50" }. Questa trasformazione è centralizzata nel BFF e non duplicata in ogni componente Vue - il che significa che se l'API del magazzino cambia il formato di risposta (un evento frequente con API legacy), correggo un file nel BFF e il frontend non se ne accorge.

Il BFF diventa anche il punto naturale per la validazione delle risposte delle API backend. Se l'API del gestionale restituisce un ordine con importo negativo (un bug nel gestionale), il BFF può intercettare l'anomalia, loggarla, e restituire al frontend un valore sanitizzato o un flag di warning. Senza BFF, quel dato anomalo arriverebbe direttamente al componente Vue e potrebbe causare un NaN nella schermata o, peggio, un calcolo errato che l'utente prende per buono. In dodici mesi di produzione, il layer di validazione del BFF ha intercettato 34 risposte anomale dalle API backend - dati che sarebbero arrivati al frontend e avrebbero generato bug visibili agli utenti o, nel caso delle fatture, errori contabili.

Deployment e monitoring del BFF

Il deployment del BFF Node.js segue lo stesso pattern che uso per i consumer Kafka e per i worker di background: un servizio systemd con restart automatico su un VPS Hetzner dedicato. Il server Express gira su una porta interna (8090) dietro il reverse proxy Nginx che gestisce anche l'applicazione PHP principale - il frontend fa le richieste al BFF attraverso lo stesso dominio, evitando problemi di CORS.

Il monitoring del BFF è cruciale perché è un single point of failure per il frontend: se il BFF è down, la dashboard non si carica. Ho integrato un health check che verifica la raggiungibilità di ciascuna delle 5 API backend ogni 30 secondi e espone un endpoint /health che il monitoring esterno (Uptime Robot o simile) controlla. Se il BFF non risponde o se più di 2 API backend su 5 sono irraggiungibili, scatta un alert. Ho applicato lo stesso pattern di monitoring minimale che descrivo nel mio articolo sull'osservabilità per applicazioni PHP legacy - il principio è identico: monitora ciò che conta, alerta solo quando serve agire.

Il BFF è in produzione da 14 mesi. Il tempo di caricamento della dashboard è stabile a 800 ms (da 7.200 ms pre-BFF), il tasso di errori visibili all'utente è sceso dal 4% (quando una delle 5 API falliva e il frontend crashava) allo 0% (il BFF gestisce i fallimenti parziali con graceful degradation), e il costo infrastrutturale del BFF è di 3,85 euro al mese - il miglior rapporto costo/beneficio di qualsiasi intervento architetturale che ho fatto per quel cliente. Il team frontend ha semplificato drasticamente il proprio codice eliminando tutta la logica di orchestrazione, retry e trasformazione dati che prima viveva nei componenti Vue - codice fragile e difficile da testare che ora è centralizzato nel BFF con test unitari e copertura al 90%. Se hai un frontend che consuma più API backend e il tempo di caricamento o la complessità della gestione degli errori stanno diventando un problema, contattami per valutare l'introduzione di un BFF: in una giornata di analisi mappiamo le API, identifichiamo le opportunità di aggregazione e caching, e progettiamo l'architettura del BFF con deployment, monitoring e test di integrazione inclusi, per un risultato in produzione in due settimane.