Validação e tratamento de erros

Uma API é julgada muito mais pelas respostas de falha do que pelas de sucesso. O caminho nominal é fácil: foi escrito primeiro, testado primeiro, demonstrado primeiro. Os erros, por sua vez, aparecem em produção, em um cliente que você não conhece, em uma situação que ninguém havia previsto — e é nesse momento que a qualidade da API se revela.

O sintoma clássico é um catálogo de inconsistências. Um identificador inexistente retorna 500 com uma página HTML de erro do Spring. Um campo obrigatório ausente retorna 400 com uma estrutura padrão do Spring ilegível. Um conflito de negócio retorna 200 com {"succes": false}. Um desenvolvedor apressado adiciona try/catch em um controller, outro adiciona @ResponseStatus em uma exceção, um terceiro retorna um Map. Seis meses depois, a equipe cliente escreveu um código diferente para cada endpoint, e ninguém mais ousa mudar nada.

A saída desse beco sem saída se resume a duas decisões. Primeiro, validar as entradas na borda da aplicação, de forma declarativa, para que nenhum dado duvidoso chegue ao serviço. Depois, centralizar a tradução das exceções em respostas HTTP em um único lugar, com um formato único. O Spring 6 fornece esse formato: ProblemDetail, a implementação da RFC 9457.