Detalles de problemas RFC 7807 y respuestas de error coherentes
Devuelva cargas útiles de error estructuradas conformes con RFC 7807 mediante ProblemDetail de Spring 6.
Detalles de problemas RFC 7807 y respuestas de error coherentes es una lección gratuita de Java Academy en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Java Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Java Academy incluye 4 lecciones en total.
¿Qué es RFC 7807?
RFC 7807, «Problem Details for HTTP APIs», define un formato JSON estándar para las respuestas de error. Evita crear formatos de error personalizados para cada API y proporciona a los clientes una estructura predecible que pueden analizar.
Campos de RFC 7807
Campos estándar: type (URI que identifica el problema), title (resumen legible para las personas), status (código de estado HTTP), detail (explicación específica), instance (URI de la incidencia concreta).
{
"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 en Spring 6
Spring 6 / Spring Boot 3 incluye compatibilidad integrada con ProblemDetail. Devuelva ProblemDetail desde los controladores de excepciones o utilice 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;
}Añadir extensiones personalizadas
ProblemDetail admite propiedades de extensión mediante setProperty(key, value) para incluir detalles específicos del dominio, como códigos de error o errores de campos.
ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
pd.setTitle("Validation Failed");
pd.setProperty("errors", fieldErrors); // custom extension
pd.setProperty("timestamp", Instant.now());Activar RFC 7807 para Spring MVC
Active ProblemDetail para todas las excepciones integradas de Spring estableciendo spring.mvc.problemdetails.enabled=true en application.properties. Spring encapsula automáticamente las excepciones estándar (404, 405, etc.) en el formato RFC 7807.
# application.properties:
spring.mvc.problemdetails.enabled=trueErrorResponseException
Lance ErrorResponseException desde el código del servicio para generar una respuesta RFC 7807 sin un método controlador; Spring MVC la captura y le da formato.
throw new ErrorResponseException(HttpStatus.CONFLICT,
ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT,
"Email already exists: " + email), null);Subclase personalizada de ProblemDetail
Cree una subclase específica del dominio de ProblemDetail para añadir campos de extensión con tipos definidos y mantener limpio el código de los controladores.
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 contenido: application/problem+json
Las respuestas RFC 7807 deben utilizar el tipo de contenido application/problem+json para que los clientes puedan distinguir las respuestas de error de las cargas JSON normales.
return ResponseEntity.status(HttpStatus.NOT_FOUND)
.contentType(MediaType.APPLICATION_PROBLEM_JSON)
.body(pd);Lista de comprobación para una estructura de errores coherente
Una API de errores adecuada incluye: (1) un URI de tipo legible por máquinas, (2) un título legible para las personas, (3) el código de estado HTTP exacto, (4) un mensaje de detalle específico, (5) el URI de instancia de la solicitud y (6) campos de extensión opcionales (timestamp, traceId, errores de campos).
IDs de traza para la observabilidad
Añada el ID de traza de la solicitud (de Micrometer Tracing o MDC) como propiedad de extensión para que los ingenieros puedan relacionar los registros de error con la solicitud concreta que falló.
pd.setProperty("traceId", MDC.get("traceId"));
pd.setProperty("timestamp", Instant.now());Probar los detalles del problema
En las pruebas de @WebMvcTest, compruebe que el tipo de contenido de la respuesta sea application/problem+json y que los campos JSON como status, title y detail coincidan con los 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"));Comprobación rápida
¿Qué propiedad de Spring Boot activa RFC 7807 para las excepciones integradas de Spring MVC?
Resumen
RFC 7807 estandariza las respuestas JSON de error con los campos type, title, status, detail e instance. Spring 6 proporciona ProblemDetail y ErrorResponseException. Actívelo con spring.mvc.problemdetails.enabled=true. Añada traceId y timestamp como extensiones para mejorar la observabilidad.
Preguntas frecuentes
¿La lección «Detalles de problemas RFC 7807 y respuestas de error coherentes» es gratis?
Sí — el texto completo de «Detalles de problemas RFC 7807 y respuestas de error coherentes» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Java Academy, actualiza a CoddyKit PRO. El curso de Java Academy incluye 4 lecciones en total.
¿Qué aprenderé en «Detalles de problemas RFC 7807 y respuestas de error coherentes»?
Devuelva cargas útiles de error estructuradas conformes con RFC 7807 mediante ProblemDetail de Spring 6. Practicas Java Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar Java Academy?
No se requiere experiencia previa. Java Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.
¿Cuánto tiempo toma la lección «Detalles de problemas RFC 7807 y respuestas de error coherentes»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de Java Academy?
Sí. Cada lección de Java Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Validación de beans: @NotNull, @Size, @Pattern
- Anotaciones de restricciones personalizadas
- Gestión global de excepciones con @ControllerAdvice
- Detalles de problemas RFC 7807 y respuestas de error coherentes