Padrão de Middleware

Construa pipelines de requisição a partir de funções pequenas e compostas que cada uma lida com uma preocupação antes de passar o controle para o próximo manipulador.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import express, { type Request, type Response, type NextFunction } from "express";
 
const app = express();
 
// Middleware é executado na ordem de registro
app.use((req, _res, next) => {
  req.headers["x-request-start"] = String(Date.now());
  next();
});
 
app.get("/users", (req, res) => {
  res.json({ startedAt: req.headers["x-request-start"] });
});
 
// Middleware de erro de quatro argumentos (Express 5)
app.use((err: Error, _req: Request, res: Response, _next: NextFunction) => {
  res.status(500).json({ error: err.message });
});

Quando usar isso: Qualquer aplicativo HTTP que precise de preocupações transversais (logging, autenticação, parsing, CORS) aplicadas consistentemente em todas as rotas.

Exemplo de Trabalho

Um executor de middleware mínimo sem Express, depois a mesma cadeia no Express 5.

import express from "express";
 
// --- Tipos de middleware Node puros ---
type Req = { headers: Record<string, string | undefined>; body?: unknown };
type Res = { statusCode: number; body?: unknown; status(n: number): Res; json(d: unknown): void };
type Next = (err?: Error) => void;
type Middleware = (req: Req, res: Res, next: Next) => void;
 
function runMiddleware(
  middlewares: Middleware[],
  req: Req,
  res: Res,
  finalHandler: () => void
) {
  let index = 0;
  const next: Next = (err) => {
    if (err) throw err;
    const fn = middlewares[index++];
    if (fn) fn(req, res, next);
    else finalHandler();
  };
  next();
}
 
// --- Equivalente do Express 5 ---
const app = express();
app.use(express.json({ limit: "1mb" }));
 
function requestId(req: express.Request, _res: express.Response, next: express.NextFunction) {
  req.headers["x-request-id"] = crypto.randomUUID();
  next();
}
 
function requireAuth(req: express.Request, res: express.Response, next: express.NextFunction) {
  const token = req.headers.authorization;
  if (!token?.startsWith("Bearer ")) {
    res.status(401).json({ error: "Unauthorized" });
    return;
  }
  next();
}
 
app.use(requestId);
app.get("/public", (_req, res) => res.json({ ok: true }));
app.get("/private", requireAuth, (_req, res) => res.json({ secret: true }));

O que isso demonstra:

• Middleware é uma função com a assinatura (req, res, next)
• Chame next() para continuar; omita para encerrar a resposta
• A ordem importa: parsers antes das rotas, manipuladores de erro por último
• Middleware de rota (requireAuth) limita a autenticação a caminhos específicos

Mergulho Profundo

Como Funciona

• Cada middleware pode mutar req/res, encerrar a resposta ou chamar next()
• A cadeia é uma invocação ligada: m1 -> m2 -> m3 -> manipulador de rota
• Middleware de erro tem 4 parâmetros (err, req, res, next) e só é executado quando next(err) é chamado
• Fastify usa hooks (onRequest, preHandler) em vez de uma única cadeia; NestJS usa guards, interceptors e pipes

Categorias de Middleware

Notas de TypeScript

// Estende o Request do Express para contexto de middleware tipado
declare global {
  namespace Express {
    interface Request {
      userId?: string;
    }
  }
}
 
function attachUser(req: express.Request, _res: express.Response, next: express.NextFunction) {
  req.userId = "user-42";
  next();
}

Armadilhas

• Chamar next() após res.send() - envia respostas duplicadas e falha com ERR_HTTP_HEADERS_SENT. Correção: retorne imediatamente após encerrar a resposta.
• next() esquecido - a requisição fica pendente até o tempo limite. Correção: cada caminho de código deve chamar next() ou encerrar a resposta.
• Middleware de erro registrado antes das rotas - nunca é executado. Correção: registre manipuladores de 4 argumentos após todas as rotas.
• Middleware assíncrono sem encaminhamento de erro - promessas rejeitadas são perdidas em padrões mais antigos. Correção: Express 5 captura erros assíncronos; caso contrário, use try/catch e next(err).
• Autenticação global em arquivos estáticos - bloqueia favicon.ico e verificações de integridade. Correção: monte a autenticação em roteadores específicos, não app.use(auth) globalmente.
• Ordem dos parsers de corpo - express.json() após as rotas significa que os corpos POST nunca são analisados. Correção: parsers primeiro. Veja Ordem de Middleware.

Alternativas

FAQs

Relacionados

• Ordem de Middleware - sequência de registro correta
• Tratamento de Erros no Express - padrões de middleware de erro
• Middleware de Segurança - helmet, cors, limites de taxa
• Guards, Interceptors & Pipes - equivalente NestJS
• Melhores Práticas de Fundamentos HTTP - checklist da seção

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.