Middleware no Express: como o next() funciona, com exemplos

Middleware no Express é uma função com a assinatura (req, res, next) que roda entre o momento em que a requisição chega e o momento em que a resposta é enviada. Cada middleware pode ler ou alterar req e res, encerrar a requisição enviando uma resposta, ou chamar next() para entregar a requisição à próxima função da fila. app.use(fn) adiciona um middleware para todas as requisições, e o Express roda tudo na ordem em que você registrou.

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

O Console registra os três passos em ordem a cada requisição, e a rota lê req.startedAt, uma propriedade que o logger adicionou. Envie GET /missing: os dois middlewares ainda registram, porque app.use() casa com qualquer caminho, e depois o Express responde 404, já que nenhuma rota correspondeu.

Esquecer o next()

Um middleware que nem envia resposta nem chama next() deixa a requisição pendurada. O cliente espera até dar timeout, e nada aparece nos logs, o que faz deste um bug de middleware comum. Apague next(); do logger acima e envie GET / de novo: a requisição nunca recebe resposta.

A regra é simples: todo caminho dentro de um middleware termina em exatamente uma destas opções:

• next() para continuar,
• next(err) para pular para o error handler (veja tratamento de erros no Express),
• uma resposta como res.json() ou res.status(401).send().

Chamar next() depois de enviar uma resposta também é bug. O próximo handler tenta enviar uma segunda resposta e o Express lança ERR_HTTP_HEADERS_SENT. Escreva return res.status(401).json(...) para a função parar ali.

Um auth check que barra a requisição

Um middleware que rejeita uma requisição envia a resposta ele mesmo e nunca chama next(). Passe ele como argumento extra de uma rota para proteger só aquela rota:

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

A primeira requisição recebe 401 com {"error":"Missing or wrong API key"}. Adicione o header x-api-key: secret123 na barra de requisição e envie de novo: agora a resposta é {"users":42,"caller":"reporting-app"}. /public nunca roda a verificação.

Onde o middleware roda

A ordem faz parte do significado. Um logger registrado depois das rotas nunca registra as requisições que essas rotas responderam, porque uma rota que envia uma resposta não chama next(). Registre primeiro os middlewares do app inteiro, como logging, parse do body e CORS, depois as rotas, depois os handlers de 404 e de erro.

Middleware nativo

O Express traz algumas funções de middleware que você adiciona com app.use(). Os body parsers preenchem req.body; sem eles, ele é 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);

Envie POST /echo com o body {"name": "Ada"} e a resposta inclui "body":{"name":"Ada"}. Remova a linha do express.json(), envie de novo, e body some da resposta: req.body é undefined, e JSON.stringify deixa valores undefined de fora. Pacotes como cors, helmet e morgan também são middleware: você faz npm install e passa para app.use() do mesmo jeito. A página do express.static cobre como servir arquivos.

Erros comuns

Chamar o middleware em vez de passá-lo. app.use(logger()) roda o logger uma vez na inicialização e registra o valor que ele retorna. Escreva app.use(logger). (express.json() tem parênteses porque retorna uma função de middleware.)

Adicionar o body parser depois das rotas. As rotas rodam primeiro e veem req.body como undefined.

Esperar que app.use('/admin', fn) case com um caminho só. Ele também roda para /admin/users e qualquer outro caminho abaixo de /admin, para todos os métodos. Para proteger uma única rota, passe o middleware para app.get('/admin', fn, handler).