Introdução (3 min)

Imagine um restaurante. Diversos problemas podem ocorrer: um pedido errado, um prato queimado, a falta de um ingrediente. Em vez de cada garçom lidar com esses problemas individualmente, existe um gerente. Ele centraliza o tratamento das questões, garantindo uma resposta consistente e profissional. Em APIs, o middleware de tratamento de erros funciona como esse gerente.

APIs modernas precisam ser robustas e confiáveis. Um bom tratamento de erros é fundamental para garantir uma experiência consistente para o usuário, independentemente do problema ocorrido. Nesta aula, você aprenderá a centralizar o tratamento de erros em sua API Node.js/Express, tornando-a mais profissional e fácil de manter.

No ecossistema Node.js/Express, middlewares são funções que interceptam requisições antes de chegarem à sua rota final. O middleware de erro é um tipo especial que lida especificamente com exceções e erros, permitindo um fluxo de controle bem definido.

Conceito Fundamental (7 min)

Um middleware de tratamento de erros centraliza a lógica para lidar com erros que ocorrem em qualquer parte da sua aplicação Express. Ele captura as exceções, formata a resposta de erro e a envia ao cliente de forma consistente, evitando repetição de código e melhorando a manutenibilidade. Na indústria, este padrão é vital para a construção de APIs resilientes.

Em cenários reais de produção, esse tipo de middleware simplifica o registro (logging), monitoramento e depuração de erros. Imagine uma API que processa pagamentos. Se ocorrer uma falha, o middleware pode registrar o erro em um serviço externo como o Sentry ou Rollbar, além de enviar uma mensagem amigável ao usuário. Ele se integra facilmente com ferramentas de logging, como o Winston ou o Pino.

A principal vantagem é a organização e a previsibilidade. A desvantagem é uma pequena sobrecarga de processamento para cada requisição, mas o benefício em termos de manutenção e clareza compensa largamente.

Implementação Prática (10 min)

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

// Simulando uma rota com erro
app.get('/erro', (req, res, next) => {
  const err = new Error('Algo deu errado!');
  err.status = 500; // Código de status HTTP
  next(err); // Passa o erro para o middleware
});
// Middleware de tratamento de erros (4 argumentos!)
app.use((err, req, res, next) => {
  console.error(err.stack); // Log do erro completo
  // Define o status de erro (ou usa 500 como padrão)
  res.status(err.status || 500);
  // Resposta JSON para o cliente
  res.json({
    erro: {
      mensagem: err.message,
      status: err.status,
      // No ambiente de produção, evite expor detalhes sensíveis
      ...(process.env.NODE_ENV !== 'production' && { stack: err.stack })
    }
  });
});
// Inicia o servidor na porta definida pelo HostGator Plano M
const port = process.env.PORT || 3000; // HostGator geralmente usa a variável de ambiente PORT
app.listen(port, () => console.log(Servidor rodando na porta ${port}));

Neste exemplo, simulamos um erro na rota /erro. O middleware captura esse erro e envia uma resposta JSON com a mensagem e o código de status. O console.error(err.stack) registra o erro no console, crucial para depuração. A condicional process.env.NODE_ENV !== 'production' garante que detalhes sensíveis do erro, como o stack trace, não sejam expostos em produção.

Adaptações para HostGator Plano M incluem o uso de process.env.PORT para a porta, uma prática comum em ambientes de hospedagem.

Exercício Hands-On (5 min)

Crie uma nova rota /usuario/:id que simula a busca de um usuário por ID. Se o ID for menor que zero, gere um erro 400 (Bad Request) com a mensagem “ID inválido”. Teste a rota com IDs válidos e inválidos.

Solução:

app.get('/usuario/:id', (req, res, next) => {
  const id = parseInt(req.params.id);
  if (id < 0) {
    const err = new Error('ID inválido');
    err.status = 400;
    return next(err); // Retorna para evitar execução posterior
  }
  // Simulando busca no banco de dados (substitua pela lógica real)
  res.json({ id, nome: 'Usuário ' + id });
});

Para testar, acesse /usuario/1 (válido) e /usuario/-1 (inválido). Observe as respostas e o console. Para aprofundar, explore outros códigos de status HTTP e diferentes tipos de erros.