Validação e Tratamento de Erros

A validação protege um limite; os invariantes do domínio protegem o estado válido em toda parte. Uma requisição sintaticamente válida ainda pode violar uma regra do caso de uso que dependa do estado atual. O guia de mapeamento e validação de DTOs separa as responsabilidades de transporte, aplicação, domínio e banco de dados.

record CreateBookRequest(
        @NotBlank @Size(max = 200) String title,
        @NotNull @PastOrPresent LocalDate publishedOn) {
}

@Valid aciona a Bean Validation aninhada para os argumentos de controller que a aceitam. Use construtores ou factories do domínio para preservar os invariantes quando objetos forem criados fora do HTTP.

Representação dos erros

O Spring Framework oferece ProblemDetail para o padrão Problem Details for HTTP APIs. Um advice centralizado pode traduzir exceções da aplicação sem expor stack traces, detalhes de SQL, nomes de classes ou segredos.

@RestControllerAdvice
final class ApiErrors {
    @ExceptionHandler(BookNotFoundException.class)
    ProblemDetail notFound(BookNotFoundException exception) {
        ProblemDetail detail = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);
        detail.setTitle("Book not found");
        detail.setDetail("No book is available for the supplied identifier.");
        return detail;
    }
}

Não retorne a mensagem bruta de uma exceção apenas por conveniência. Defina um tipo ou código de erro estável quando os clientes precisarem tomar decisões com base nele.

Taxonomia de falhas

• representação malformada ou incompatibilidade de tipo: erro na requisição do cliente;
• violação de restrição de campo: erro de validação estruturado;
• recurso ausente: ausência segundo a política de divulgação da API;
• conflito de estado: entrada válida incompatível com o estado atual;
• timeout ou indisponibilidade de dependência: falha transitória no servidor;
• defeito inesperado: erro genérico de servidor e um identificador interno de correlação.

Consulte a documentação oficial de validação do Spring MVC e de respostas de erro.