Middleware w Express: jak działa next(), z przykładami

Middleware w Express to funkcja o sygnaturze (req, res, next), która działa między chwilą, w której przychodzi żądanie, a chwilą wysłania odpowiedzi. Każdy middleware może odczytać lub zmienić req i res, zakończyć żądanie, wysyłając odpowiedź, albo wywołać next(), żeby przekazać żądanie kolejnej funkcji w kolejce. app.use(fn) dodaje middleware dla każdego żądania, a Express wykonuje wszystko w kolejności rejestracji.

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);

Console przy każdym żądaniu wypisuje trzy kroki po kolei, a trasa odczytuje req.startedAt, właściwość dodaną przez logger. Wyślij GET /missing: oba middleware i tak logują, bo app.use() pasuje do każdej ścieżki, a potem Express odpowiada 404, bo żadna trasa nie pasowała.

Zapomniane next()

Middleware, który ani nie wysyła odpowiedzi, ani nie wywołuje next(), zostawia żądanie zawieszone. Klient czeka do timeoutu, a w logach nic się nie pojawia, dlatego to częsty błąd w middleware. Usuń next(); z logger powyżej i wyślij jeszcze raz GET /: żądanie nigdy nie dostanie odpowiedzi.

Zasada jest prosta: każda ścieżka przez middleware kończy się dokładnie jednym z tych wywołań:

• next(), żeby iść dalej,
• next(err), żeby przeskoczyć do error handlera (zobacz obsługę błędów w Express),
• odpowiedzią, np. res.json() albo res.status(401).send().

Wywołanie next() po wysłaniu odpowiedzi to też błąd. Następny handler próbuje wysłać drugą odpowiedź, a Express rzuca ERR_HTTP_HEADERS_SENT. Pisz return res.status(401).json(...), żeby funkcja się tam zatrzymała.

Sprawdzanie autoryzacji, które zatrzymuje żądanie

Middleware, który odrzuca żądanie, sam wysyła odpowiedź i nigdy nie wywołuje next(). Przekaż go trasie jako dodatkowy argument, żeby chronić tylko tę trasę:

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);

Pierwsze żądanie dostaje 401 z {"error":"Missing or wrong API key"}. Dodaj w pasku żądania nagłówek x-api-key: secret123 i wyślij jeszcze raz: teraz odpowiedź to {"users":42,"caller":"reporting-app"}. /public nigdy nie uruchamia tego sprawdzenia.

Gdzie działa middleware

Kolejność jest częścią znaczenia. Logger zarejestrowany po trasach nigdy nie zaloguje żądań, na które te trasy odpowiedziały, bo trasa, która wysyła odpowiedź, nie wywołuje next(). Najpierw rejestruj middleware dla całej aplikacji, np. logowanie, parsowanie body i CORS, potem trasy, a na końcu handlery 404 i błędów.

Wbudowane middleware

Express ma kilka funkcji middleware, które dodajesz przez app.use(). Parsery body wypełniają req.body; bez nich jest 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);

Wyślij POST /echo z body {"name": "Ada"}, a odpowiedź zawiera "body":{"name":"Ada"}. Usuń linię express.json(), wyślij jeszcze raz, a body zniknie z odpowiedzi: req.body to undefined, a JSON.stringify pomija wartości undefined. Pakiety takie jak cors, helmet i morgan to też middleware: instalujesz je przez npm install i przekazujesz do app.use() w ten sam sposób. Serwowanie plików opisuje strona o express.static.

Częste błędy

Wywoływanie middleware zamiast przekazywania go. app.use(logger()) uruchamia logger raz przy starcie i rejestruje to, co zwrócił. Pisz app.use(logger). (express.json() ma nawiasy, bo zwraca funkcję middleware.)

Dodanie parsera body po trasach. Trasy wykonują się pierwsze i widzą req.body jako undefined.

Oczekiwanie, że app.use('/admin', fn) pasuje do jednej ścieżki. Działa też dla /admin/users i każdej innej ścieżki pod /admin, dla każdej metody. Żeby chronić pojedynczą trasę, przekaż middleware do app.get('/admin', fn, handler).