Middleware Express: come funziona next(), con esempi

In Express un middleware è una funzione con la firma (req, res, next) che viene eseguita tra l'arrivo di una richiesta e l'invio della risposta. Ogni middleware può leggere o modificare req e res, chiudere la richiesta inviando una risposta, o chiamare next() per passare la richiesta alla funzione successiva. app.use(fn) aggiunge un middleware per ogni richiesta, ed Express esegue tutto nell'ordine in cui l'hai registrato.

const express = require('express');
const app = express();

function logger(req, res, next) {
    req.startedAt = Date.now();
    console.log('1. logger:', req.method, req.url);
    next();
}

app.use(logger);

app.use((req, res, next) => {
    console.log('2. second middleware');
    next();
});

app.get('/', (req, res) => {
    console.log('3. route handler');
    res.json({ ok: true, tookMs: Date.now() - req.startedAt });
});

app.listen(3000);

La Console mostra i tre passaggi in ordine per ogni richiesta, e la route legge req.startedAt, una proprietà aggiunta dal logger. Invia GET /missing: i due middleware scrivono comunque il log, perché app.use() corrisponde a ogni path, poi Express risponde 404 dato che nessuna route corrisponde.

Dimenticare next()

Un middleware che non invia una risposta e non chiama next() lascia la richiesta appesa. Il client aspetta fino al timeout e nei log non compare niente, per questo è un bug comune con i middleware. Cancella next(); dal logger qui sopra e invia di nuovo GET /: la richiesta non riceve mai risposta.

La regola è semplice: ogni percorso dentro un middleware finisce con esattamente una di queste cose:

• next() per continuare,
• next(err) per saltare all'error handler (vedi la gestione degli errori in Express),
• una risposta come res.json() o res.status(401).send().

Anche chiamare next() dopo aver inviato una risposta è un bug. L'handler successivo prova a inviare una seconda risposta ed Express lancia ERR_HTTP_HEADERS_SENT. Scrivi return res.status(401).json(...) così la funzione si ferma lì.

Un controllo di accesso che ferma la richiesta

Un middleware che rifiuta una richiesta invia la risposta da solo e non chiama mai next(). Passalo come argomento in più a una route per proteggere solo quella:

const express = require('express');
const app = express();

function requireApiKey(req, res, next) {
    if (req.get('x-api-key') !== 'secret123') {
        return res.status(401).json({ error: 'Missing or wrong API key' });
    }
    req.client = 'reporting-app';
    next();
}

app.get('/public', (req, res) => {
    res.json({ message: 'Anyone can read this' });
});

app.get('/admin/stats', requireApiKey, (req, res) => {
    res.json({ users: 42, caller: req.client });
});

// GET /admin/stats
app.listen(3000);

La prima richiesta riceve 401 con {"error":"Missing or wrong API key"}. Aggiungi l'header x-api-key: secret123 nella barra della richiesta e inviala di nuovo: ora la risposta è {"users":42,"caller":"reporting-app"}. /public non esegue mai il controllo.

Dove viene eseguito un middleware

L'ordine fa parte del significato. Un logger registrato dopo le route non scrive mai le richieste a cui quelle route hanno risposto, perché una route che invia una risposta non chiama next(). Registra prima i middleware globali come logging, parsing del body e CORS, poi le route, poi gli handler 404 e degli errori.

I middleware integrati

Express include alcuni middleware da aggiungere con app.use(). I body parser riempiono req.body; senza di loro è undefined.

const express = require('express');
const app = express();

app.use(express.json());
app.use(express.urlencoded());

app.get('/', (req, res) => {
    res.send('Send POST /echo with a body');
});

app.post('/echo', (req, res) => {
    res.json({ type: req.get('content-type'), body: req.body });
});

app.listen(3000);

Invia POST /echo con il body {"name": "Ada"} e la risposta contiene "body":{"name":"Ada"}. Togli la riga express.json(), inviala di nuovo, e body sparisce dalla risposta: req.body è undefined e JSON.stringify omette i valori undefined. Anche pacchetti come cors, helmet e morgan sono middleware: li installi con npm install e li passi ad app.use() nello stesso modo. La pagina su express.static spiega come servire file.

Errori comuni

Chiamare il middleware invece di passarlo. app.use(logger()) esegue logger una volta all'avvio e registra il suo valore di ritorno. Scrivi app.use(logger). (express.json() ha le parentesi perché restituisce una funzione middleware.)

Aggiungere il body parser dopo le route. Le route girano per prime e vedono req.body come undefined.

Aspettarsi che app.use('/admin', fn) corrisponda a un solo path. Viene eseguito anche per /admin/users e per ogni altro path sotto /admin, con ogni metodo. Per proteggere una sola route, passa il middleware ad app.get('/admin', fn, handler).