Padrões de Tratamento de Erros

Crie aplicações resilientes com estratégias robustas de tratamento de erros que lidam graciosamente com falhas e proporcionam excelentes experiências de depuração.

Quando Usar Esta Habilidade

• Implementar tratamento de erros em novos recursos
• Projetar APIs resilientes a erros
• Depurar problemas em produção
• Melhorar a confiabilidade da aplicação
• Criar melhores mensagens de erro para usuários e desenvolvedores
• Implementar padrões de retentativa e disjuntor (circuit breaker)
• Lidar com erros assíncronos/concorrentes
• Construir sistemas distribuídos tolerantes a falhas

Conceitos Principais

1. Filosofias de Tratamento de Erros

Exceções vs. Tipos de Resultado (Result Types):

• Exceções: Tradicional try-catch, interrompe o fluxo de controle
• Tipos de Resultado: Sucesso/falha explícitos, abordagem funcional
• Códigos de Erro: Estilo C, requer disciplina
• Tipos Option/Maybe: Para valores nulos (nullable)

Quando Usar Cada Um:

• Exceções: Erros inesperados, condições excepcionais
• Tipos de Resultado: Erros esperados, falhas de validação
• Pânicos/Travamentos: Erros irrecuperáveis, bugs de programação

2. Categorias de Erros

Erros Recuperáveis:

• Tempo limite de rede (Network timeouts)
• Arquivos ausentes
• Entrada inválida do usuário
• Limites de taxa de API (API rate limits)

Erros Irrecuperáveis:

• Falta de memória (Out of memory)
• Estouro de pilha (Stack overflow)
• Bugs de programação (ponteiro nulo, etc.)

Padrões Detalhados e Exemplos Práticos

A documentação detalhada dos padrões está em references/details.md. Leia este arquivo quando o nível de navegação acima for insuficiente.

Melhores Práticas

1. Falhar Rapidamente (Fail Fast): Valide a entrada cedo, falhe rapidamente
2. Preservar Contexto: Inclua rastros de pilha (stack traces), metadados, carimbos de data/hora
3. Mensagens Significativas: Explique o que aconteceu e como corrigir
4. Registrar (Log) Apropriadamente: Erro = registrar, falha esperada = não encher os logs
5. Tratar no Nível Certo: Capture onde você pode tratar de forma significativa
6. Limpar Recursos: Use try-finally, gerenciadores de contexto, defer
7. Não Engolir Erros: Registre ou relance, não ignore silenciosamente
8. Erros Tipados (Type-Safe Errors): Use erros tipados quando possível

# Good error handling example
def process_order(order_id: str) -> Order:
    """Process order with comprehensive error handling."""
    try:
        # Validate input
        if not order_id:
            raise ValidationError("Order ID is required")

        # Fetch order
        order = db.get_order(order_id)
        if not order:
            raise NotFoundError("Order", order_id)

        # Process payment
        try:
            payment_result = payment_service.charge(order.total)
        except PaymentServiceError as e:
            # Log and wrap external service error
            logger.error(f"Payment failed for order {order_id}: {e}")
            raise ExternalServiceError(
                f"Payment processing failed",
                service="payment_service",
                details={"order_id": order_id, "amount": order.total}
            ) from e

        # Update order
        order.status = "completed"
        order.payment_id = payment_result.id
        db.save(order)

        return order

    except ApplicationError:
        # Re-raise known application errors
        raise
    except Exception as e:
        # Log unexpected errors
        logger.exception(f"Unexpected error processing order {order_id}")
        raise ApplicationError(
            "Order processing failed",
            code="INTERNAL_ERROR"
        ) from e

Armadilhas Comuns

• Capturar de Forma Muito Ampla: except Exception esconde bugs
• Blocos Catch Vazios: Engolindo erros silenciosamente
• Registrar e Relançar: Cria entradas de log duplicadas
• Não Limpar: Esquecer de fechar arquivos, conexões
• Mensagens de Erro Ruins: "Ocorreu um erro" não é útil
• Retornar Códigos de Erro: Use exceções ou tipos de resultado
• Ignorar Erros Assíncronos: Rejeições de promessa não tratadas