0Pricing
Java Academy · Aula

Detalhes de problemas RFC 7807 e respostas de erro consistentes

Retorne cargas de erro estruturadas em conformidade com a RFC 7807 usando ProblemDetail do Spring 6.

Detalhes de problemas RFC 7807 e respostas de erro consistentes é uma aula grátis de Java Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Java Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Java Academy inclui 4 aulas no total.

O que é RFC 7807?

A RFC 7807, «Detalhes de problemas para APIs HTTP», define um formato JSON padrão para respostas de erro. Ela evita formatos de erro personalizados para cada API e fornece aos clientes uma estrutura previsível para análise.

Campos da RFC 7807

Campos padrão: type (URI que identifica o problema), title (resumo legível por humanos), status (código de status HTTP), detail (explicação específica), instance (URI da ocorrência específica).

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "User with id 42 does not exist.",
  "instance": "/api/users/42"
}

ProblemDetail do Spring 6

O Spring 6 / Spring Boot 3 inclui suporte integrado a ProblemDetail. Retorne ProblemDetail nos manipuladores de exceções ou use ErrorResponseException.

import org.springframework.http.ProblemDetail;

@ExceptionHandler(ResourceNotFoundException.class)
public ProblemDetail handleNotFound(ResourceNotFoundException ex, HttpServletRequest req) {
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
    pd.setType(URI.create("https://api.example.com/errors/not-found"));
    pd.setTitle("Resource Not Found");
    pd.setInstance(URI.create(req.getRequestURI()));
    return pd;
}

Adicionando extensões personalizadas

ProblemDetail oferece suporte a propriedades de extensão por meio de setProperty(key, value) para detalhes específicos do domínio, como códigos de erro ou erros de campo.

ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
pd.setTitle("Validation Failed");
pd.setProperty("errors", fieldErrors); // custom extension
pd.setProperty("timestamp", Instant.now());

Ativando a RFC 7807 para o Spring MVC

Ative ProblemDetail para todas as exceções integradas do Spring definindo spring.mvc.problemdetails.enabled=true em application.properties. O Spring então encapsula automaticamente as exceções padrão (404, 405 etc.) no formato da RFC 7807.

# application.properties:
spring.mvc.problemdetails.enabled=true

ErrorResponseException

Lance ErrorResponseException a partir do código do serviço para produzir uma resposta RFC 7807 sem um método manipulador — o Spring MVC a captura e formata.

throw new ErrorResponseException(HttpStatus.CONFLICT,
    ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT,
        "Email already exists: " + email), null);

Subclasse personalizada de ProblemDetail

Crie uma subclasse específica do domínio de ProblemDetail para adicionar campos de extensão tipados e manter o código do manipulador limpo.

public class ValidationProblemDetail extends ProblemDetail {
    private final Map<String, String> fieldErrors;
    public ValidationProblemDetail(Map<String, String> errors) {
        super(HttpStatus.BAD_REQUEST.value());
        this.fieldErrors = errors;
        setTitle("Validation Failed");
        setProperty("fieldErrors", errors);
    }
}

Tipo de conteúdo: application/problem+json

As respostas RFC 7807 devem usar o tipo de conteúdo application/problem+json para que os clientes possam distinguir respostas de problemas de cargas JSON normais.

return ResponseEntity.status(HttpStatus.NOT_FOUND)
    .contentType(MediaType.APPLICATION_PROBLEM_JSON)
    .body(pd);

Lista de verificação para uma estrutura de erro consistente

Uma boa API de erros contém: (1) URI de tipo legível por máquina, (2) título legível por humanos, (3) código de status HTTP exato, (4) mensagem de detalhes específica, (5) URI da instância da solicitação, (6) campos de extensão opcionais (marca de data e hora, traceId, erros de campo).

IDs de rastreamento para observabilidade

Adicione o ID de rastreamento da solicitação (do Micrometer Tracing ou MDC) como uma propriedade de extensão para que os engenheiros possam correlacionar os registros de erros com a solicitação específica que falhou.

pd.setProperty("traceId", MDC.get("traceId"));
pd.setProperty("timestamp", Instant.now());

Testando detalhes de problemas

Nos testes com @WebMvcTest, verifique se o tipo de conteúdo da resposta é application/problem+json e se campos JSON como status, title e detail correspondem aos valores esperados.

mockMvc.perform(get("/api/users/999"))
    .andExpect(status().isNotFound())
    .andExpect(content().contentType("application/problem+json"))
    .andExpect(jsonPath("$.status").value(404))
    .andExpect(jsonPath("$.title").value("Resource Not Found"));

Verificação rápida

Qual propriedade do Spring Boot ativa a RFC 7807 para as exceções integradas do Spring MVC?

Recapitulação

A RFC 7807 padroniza as respostas JSON de erro com os campos type, title, status, detail e instance. O Spring 6 fornece ProblemDetail e ErrorResponseException. Ative-a com spring.mvc.problemdetails.enabled=true. Adicione traceId e uma marca de data e hora como extensões para melhorar a observabilidade.

Perguntas Frequentes

A aula “Detalhes de problemas RFC 7807 e respostas de erro consistentes” é grátis?

Sim — o texto completo de “Detalhes de problemas RFC 7807 e respostas de erro consistentes” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Java Academy, atualize para CoddyKit PRO. O curso de Java Academy inclui 4 aulas no total.

O que vou aprender em “Detalhes de problemas RFC 7807 e respostas de erro consistentes”?

Retorne cargas de erro estruturadas em conformidade com a RFC 7807 usando ProblemDetail do Spring 6. Você pratica Java Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Java Academy?

Nenhuma experiência prévia é necessária. Java Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Detalhes de problemas RFC 7807 e respostas de erro consistentes”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Java Academy?

Sim. Cada aula de Java Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Validação de beans: @NotNull, @Size, @Pattern
  2. Anotações de restrição personalizadas
  3. Tratamento global de exceções com @ControllerAdvice
  4. Detalhes de problemas RFC 7807 e respostas de erro consistentes
← Voltar para Java Academy