PMQ.ErrorHandling

829 downloads · o maior da suíte · repositório

Tratamento centralizado de erro em ASP.NET Core: filtro de exceção, mapeamento de notificação, validação de estado de modelo e resposta padronizada.

O problema

Cada API responde erro do seu jeito. Uma devolve string, outra um objeto com message, outra o stack trace inteiro em produção. Quem integra precisa tratar cada uma de um jeito, e o log de quem consome fica inútil.

A decisão: adotar padrão em vez de inventar formato

A resposta segue RFC 9457, a especificação de problem details: tipo, título, status, detalhe, instância, mais extensão para os erros de campo. Cliente que conhece o padrão já sabe ler, e não existe documento a manter explicando um formato caseiro.

O mapeamento que fecha o ciclo da suíte

A categoria da notificação vira o código HTTP. É aqui que a decisão tomada no domínio, três camadas atrás, chega ao consumidor da API sem ninguém traduzir no meio:

NotificationType when firstNotificationType == NotificationType.NotFound
    => StatusCodes.Status404NotFound,
NotificationType when firstNotificationType == NotificationType.AccessDenied
    => StatusCodes.Status403Forbidden,
NotificationType when firstNotificationType == NotificationType.InconsistentState
    => StatusCodes.Status409Conflict,
NotificationType when firstNotificationType == NotificationType.BusinessRule
    => StatusCodes.Status422UnprocessableEntity,
NotificationType when firstNotificationType == NotificationType.Validation
    => StatusCodes.Status400BadRequest,
_   => StatusCodes.Status422UnprocessableEntity

Duas escolhas que eu defendo nesse trecho:

422 para regra de negócio, 400 para validação. A distinção é real e quase sempre ignorada: 400 é “a requisição está malformada”, 422 é “a requisição está bem formada e eu me recuso a processá-la”. Cliente que recebe 400 tenta corrigir o formato; quem recebe 422 sabe que o formato está certo e o problema é a regra.

O _ cai em 422, não em 500. Categoria desconhecida é, por definição, uma regra que a biblioteca não conhece, e não uma falha do servidor. Cair em 500 transformaria regra de negócio nova em alarme de infraestrutura.