Interceptor avvolgono l'esecuzione di un route handler, permettendoti di eseguire logica prima e dopo — e trasformare la richiesta o la risposta. Sono ispirati dalla programmazione aspect-oriented, ideali per cross-cutting concerns come logging, trasformazione della risposta, caching e timing.
()
{
(: , : ): <> {
.();
now = .();
next.().(
( .()),
);
}
}
Un interceptor implementa intercept(). Il codice prima di next.handle() viene eseguito prima dell'handler; next.handle() restituisce un Observable RxJS della risposta, e operatori come tap/map ti permettono di agire sulla risposta dopo che l'handler è completato.
@Injectable()
export class TransformInterceptor implements NestInterceptor {
intercept(context: ExecutionContext, next: CallHandler) {
return next.handle().pipe(
map(data => ({ success: true, data, timestamp: new Date().toISOString() })),
// wraps EVERY response in a consistent envelope: { success, data, timestamp }
);
}
}
Usando map, un interceptor può ristrutturare ogni risposta — ad es. avvolgendo tutte le risposte in un envelope standard, un pattern molto comune per risposte API coerenti.
// caching — return a cached response, skipping the handler entirely
// timeout — fail requests taking too long
return next.handle().pipe(timeout(5000));
// error mapping — transform exceptions
return next.handle().pipe(catchError(err => throwError(() => new BadGatewayException())));
// excluding fields (serialization) — ClassSerializerInterceptor strips @Exclude() fields
Common interceptor uses:
✓ Logging / timing requests (before + after)
✓ Transforming responses (consistent envelopes, field exclusion)
✓ Caching responses
✓ Adding timeouts
✓ Mapping/handling errors
@UseInterceptors(LoggingInterceptor) // method or controller level
app.useGlobalInterceptors(new TransformInterceptor()); // global
Middleware → runs BEFORE everything, with raw req/res (can't easily touch the response)
Guard → AUTHORIZATION decision (allow/block) before the handler
Interceptor → wraps the handler — runs BEFORE and AFTER, can TRANSFORM the response
La caratteristica distintiva: gli interceptor possono eseguire logica dopo l'handler e trasformare la risposta — cosa che middleware e guard non possono fare facilmente.
Gli interceptor sono una potente funzionalità di NestJS per gestire cross-cutting concerns elegantemente, e la loro capacità distintiva — eseguire logica sia prima che dopo l'handler, e trasformare la risposta — li rende lo strumento giusto per esigenze che middleware e guard non riescono ad affrontare.
Capirli è importante perché molti requisiti comuni si mappano naturalmente agli interceptor: formattazione coerente della risposta (avvolgere tutte le risposte in un envelope standard { success, data }), logging/timing (misurare la durata dell'handler), caching (restituire risposte in cache), timeout, trasformazione degli errori e serializzazione (escludere campi sensibili).
Conoscere la struttura (l'Observable di next.handle(), con tap/map/catchError per agire prima/dopo), i casi d'uso comuni, e soprattutto come gli interceptor differiscono da middleware e guard (la capacità di avvolgere e trasformare la risposta) è una parte chiave della competenza architettonica di NestJS.
Gli interceptor mantengono la logica cross-cutting DRY e centralizzata piuttosto che duplicata tra gli handler, rendendoli uno strumento frequentemente utilizzato e importante per costruire applicazioni NestJS pulite e manutenibili.