mkdir error-handling-api
cd error-handling-api
npm init -y
npm install express dotenv winston

📋 Copiar

// index.js

// Importa o módulo Express, essencial para criar nossa aplicação web.
const express = require('express');
// O dotenv é utilizado para carregar variáveis de ambiente de um arquivo .env.
// Isso é crucial para configurações como portas e credenciais, mantendo-as fora do código fonte.
require('dotenv').config();
// O Winston é uma biblioteca de logging robusta e flexível.
// É uma prática enterprise essencial para registrar eventos, erros e depuração.
const winston = require('winston');
// --- 1. Configuração do Logger Profissional (Winston) ---
// Criamos uma instância do logger.
const logger = winston.createLogger({
    // Nível de log: 'info' significa que mensagens de info, warn, error serão logadas.
    // Em produção, 'info' ou 'warn' são comuns. Para depuração, 'debug'.
    level: 'info',
    // Define os formatos das mensagens de log.
    // combine: Combina vários formatos.
    // timestamp: Adiciona a data e hora ao log.
    // errors: Garante que objetos Error sejam formatados corretamente (incluindo stack trace).
    // json: Formata a saída como JSON, excelente para sistemas de monitoramento de logs.
    format: winston.format.combine(
        winston.format.timestamp(),
        winston.format.errors({ stack: true }), // Inclui o stack trace para erros
        winston.format.json()
    ),
    // Define os "transportes" (onde os logs serão enviados).
    // File: Salva logs em um arquivo, uma prática standard para auditoria e depuração.
    // Console: Exibe logs no console, útil durante o desenvolvimento.
    transports: [
        new winston.transports.File({ filename: 'error.log', level: 'error' }), // Logs de erro vão para 'error.log'
        new winston.transports.File({ filename: 'combined.log' }), // Todos os logs (info, warn, error) vão para 'combined.log'
        new winston.transports.Console({
            // Formato para o console, mais legível para humanos.
            format: winston.format.combine(
                winston.format.colorize(), // Cores para diferentes níveis de log
                winston.format.simple() // Formato simples e conciso
            )
        })
    ],
    // ExitOnError é false para que o logger não saia do processo em caso de erro no transporte.
    exitOnError: false,
});
// --- 2. Definição de Erros Personalizados (Custom Errors) ---
// É uma prática enterprise criar classes de erro específicas para diferentes cenários.
// Isso permite uma melhor categorização e tratamento de erros na aplicação.
class CustomError extends Error {
    constructor(message, statusCode = 500, details = {}) {
        // Chama o construtor da classe pai (Error) com a mensagem.
        super(message);
        // Garante que o nome da classe seja o nome do erro, útil para rastreamento.
        this.name = this.constructor.name;
        // Adiciona um código de status HTTP, essencial para respostas de API.
        this.statusCode = statusCode;
        // Detalhes adicionais que podem ajudar na depuração ou informar o cliente.
        this.details = details;
        // Captura o stack trace, importante para depuração.
        Error.captureStackTrace(this, this.constructor);
    }
}
// Erro específico para validação de dados de entrada.
class ValidationError extends CustomError {
    constructor(message = 'Dados de entrada inválidos.', details = {}) {
        super(message, 400, details); // Status 400 Bad Request
    }
}
// Erro específico para recursos não encontrados.
class NotFoundError extends CustomError {
    constructor(message = 'Recurso não encontrado.', details = {}) {
        super(message, 404, details); // Status 404 Not Found
    }
}
// --- 3. Inicialização do Aplicativo Express ---
const app = express();
// Middleware para analisar corpos de requisição JSON.
// Necessário para receber dados JSON em requisições POST/PUT.
app.use(express.json());
// --- 4. Rota de Exemplo com try/catch e throw ---
// Rota POST para simular o cadastro de um usuário.
app.post('/usuarios', (req, res, next) => {
    try {
        // Desestruturação para obter 'nome' e 'email' do corpo da requisição.
        const { nome, email } = req.body;
        // --- Validação de Entrada Robusta ---
        // Aqui, usamos o operador 'throw' para lançar erros personalizados
        // se as condições de validação não forem atendidas.
        if (!nome || typeof nome !== 'string' || nome.trim().length < 3) {
            // Lança um ValidationError se o nome for inválido.
            // Isso demonstra como 'throw' é usado para sinalizar problemas lógicos.
            throw new ValidationError('O campo "nome" é obrigatório e deve ter pelo menos 3 caracteres.', { field: 'nome' });
        }
        if (!email || !email.includes('@') || !email.includes('.')) {
            // Lança um ValidationError se o email for inválido.
            throw new ValidationError('O campo "email" é obrigatório e deve ser um email válido.', { field: 'email' });
        }
        // --- Simulação de uma Operação que Pode Falhar ---
        // Por exemplo, uma tentativa de salvar no banco de dados.
        // Simulamos um cenário onde o banco de dados está "cheio" ou "offline".
        if (email === '[email protected]') {
            // Lança um erro genérico (ou um CustomError mais específico, se houvesse um DbError)
            // para simular uma falha interna, que será capturada pelo catch.
            throw new Error('Falha simulada ao salvar usuário no banco de dados.');
        }
        // Se tudo estiver OK, simulamos o salvamento e retornamos sucesso.
        const novoUsuario = { id: Date.now(), nome, email };
        logger.info(Usuário cadastrado com sucesso: ${JSON.stringify(novoUsuario)});
        // Resposta de sucesso com status 201 Created.
        res.status(201).json({
            message: 'Usuário cadastrado com sucesso!',
            data: novoUsuario
        });
    } catch (error) {
        // O bloco 'catch' é executado se qualquer 'throw' ocorrer ou se uma exceção for levantada
        // dentro do bloco 'try'.
        // O método 'next(error)' passa o erro para o próximo middleware de tratamento de erros.
        // Isso é o padrão do Express para lidar com erros de forma centralizada.
        next(error);
    }
});
// Rota para simular busca de recurso que pode não existir.
app.get('/recursos/:id', (req, res, next) => {
    try {
        const { id } = req.params;
        // Simula a busca de um recurso.
        if (id === '404') {
            // Lança um NotFoundError se o recurso não for encontrado.
            throw new NotFoundError(Recurso com ID ${id} não foi encontrado.);
        }
        // Retorna sucesso para outros IDs.
        res.status(200).json({ message: Recurso ${id} encontrado com sucesso!, data: { id, description: 'Exemplo de recurso' } });
    } catch (error) {
        next(error);
    }
});
// --- 5. Middleware Global de Tratamento de Erros (Enterprise Pattern) ---
// Este é o coração do tratamento de erros centralizado no Express.
// Ele deve ser o ÚLTIMO middleware a ser definido.
// A assinatura (err, req, res, next) o identifica como um middleware de erro.
app.use((err, req, res, next) => {
    // Registra o erro completo no logger. Isso é crucial para depuração e monitoramento.
    // Usamos 'logger.error' para garantir que vá para o arquivo de erro.
    logger.error(Ocorreu um erro: ${err.message}, {
        stack: err.stack, // Inclui o stack trace completo
        name: err.name,
        statusCode: err.statusCode || 500, // Captura o status code do erro personalizado
        url: req.originalUrl,
        method: req.method,
        body: req.body, // Pode ser útil para erros de validação
        ip: req.ip
    });
    // Define o status HTTP da resposta.
    // Prioriza o statusCode definido em nossos CustomErrors, senão usa 500 (Internal Server Error).
    const statusCode = err.statusCode || 500;
    // Mensagem para o cliente. Evitamos expor detalhes internos em erros 500 genéricos.
    const message = statusCode === 500
        ? 'Ocorreu um erro interno no servidor.' // Mensagem genérica para erros internos.
        : err.message; // Mensagem específica para outros erros (ex: validação, não encontrado).
    // Corpo da resposta de erro.
    const errorResponse = {
        success: false,
        message: message,
        code: err.name || 'InternalServerError' // Nome do erro (ex: ValidationError)
    };
    // Adiciona detalhes do erro personalizado se existirem e não for um erro interno genérico.
    if (err.details && statusCode !== 500) {
        errorResponse.details = err.details;
    }
    // Envia a resposta JSON ao cliente.
    res.status(statusCode).json(errorResponse);
});
// --- 6. Inicialização do Servidor ---
// A porta é definida por uma variável de ambiente (PORT) ou padrão 3000.
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    logger.info(Servidor Express rodando na porta ${PORT});
    logger.info(Aplicação pronta para receber requisições.);
});
// --- Configurações específicas para HostGator Plano M ---
// O HostGator Plano M geralmente roda Node.js via Phusion Passenger ou similar.
// A instalação e execução de aplicativos Node.js são padrão.
// O importante é garantir que seu package.json tenha um script 'start' que aponte para 'node index.js'
// e que suas dependências estejam listadas corretamente.
// O arquivo .env deve ser configurado separadamente ou as variáveis passadas no ambiente do servidor.
// O uso do Winston para logging em arquivos é ideal, pois os logs podem ser acessados via FTP/SSH.
// Certifique-se de que o diretório onde os logs serão gravados tenha permissões de escrita.

📋 Copiar

// package.json (exemplo)
{
  "name": "error-handling-api",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "dotenv": "^16.4.5",
    "express": "^4.19.2",
    "winston": "^3.13.0"
  }
}

📋 Copiar

PORT=3000

📋 Copiar

    node index.js

📋 Copiar

    curl -X POST -H "Content-Type: application/json" -d '{"nome":"Alice Silva", "email":"[email protected]"}' http://localhost:3000/usuarios

📋 Copiar

    curl -X POST -H "Content-Type: application/json" -d '{"nome":"Al", "email":"[email protected]"}' http://localhost:3000/usuarios

📋 Copiar

    curl -X POST -H "Content-Type: application/json" -d '{"nome":"Carlos", "email":"carlos_invalido"}' http://localhost:3000/usuarios

📋 Copiar

    curl -X POST -H "Content-Type: application/json" -d '{"nome":"Daniel", "email":"[email protected]"}' http://localhost:3000/usuarios

📋 Copiar

    curl http://localhost:3000/recursos/404

📋 Copiar

    curl http://localhost:3000/recursos/123

📋 Copiar

    // No mesmo local onde você definiu ValidationError e NotFoundError
    class DivisionByZeroError extends CustomError {
        constructor(message = 'Não é possível dividir por zero.', details = {}) {
            super(message, 400, details); // Status 400 Bad Request
        }
    }

📋 Copiar

    // ... (depois das outras rotas, antes do middleware de erro)

    // Rota GET para simular uma calculadora de divisão.
    app.get('/dividir', (req, res, next) => {
        try {
            // Obtém os parâmetros 'a' e 'b' da query string e converte para número.
            // O operador '+' tenta converter a string para número.
            const a = +req.query.a;
            const b = +req.query.b;
            // --- Validação de Entrada ---
            // Verifica se 'a' e 'b' são realmente números e se não são NaN (Not a Number).
            if (isNaN(a) || typeof req.query.a === 'undefined') {
                throw new ValidationError('O parâmetro "a" é obrigatório e deve ser um número.', { field: 'a' });
            }
            if (isNaN(b) || typeof req.query.b === 'undefined') {
                throw new ValidationError('O parâmetro "b" é obrigatório e deve ser um número.', { field: 'b' });
            }
            // --- Lançamento de Erro Personalizado para Divisão por Zero ---
            if (b === 0) {
                // Lança nosso erro específico de divisão por zero.
                throw new DivisionByZeroError('O divisor não pode ser zero.');
            }
            // Realiza a divisão.
            const resultado = a / b;
            // Retorna o resultado com sucesso.
            res.status(200).json({
                message: 'Operação de divisão realizada com sucesso!',
                data: { a, b, resultado }
            });
        } catch (error) {
            // Captura qualquer erro (ValidationError, DivisionByZeroError, ou outros)
            // e o passa para o middleware global de tratamento de erros.
            next(error);
        }
    });

📋 Copiar

    curl http://localhost:3000/dividir?a=10&b=2

📋 Copiar

    curl http://localhost:3000/dividir?a=10&b=0

📋 Copiar

    curl http://localhost:3000/dividir?b=5

📋 Copiar

    curl http://localhost:3000/dividir?a=10&b=xyz

📋 Copiar