Szczegóły problemu RFC 7807 i spójne odpowiedzi błędów
Proszę zwracać ustrukturyzowane dane błędów zgodne z RFC 7807, używając ProblemDetail z Spring 6.
Szczegóły problemu RFC 7807 i spójne odpowiedzi błędów to bezpłatna lekcja Java Academy na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Java Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Java Academy zawiera 4 lekcji w sumie.
Czym jest RFC 7807?
RFC 7807 „Problem Details for HTTP APIs” definiuje standardowy format JSON dla odpowiedzi z błędami. Eliminuje potrzebę stosowania niestandardowych formatów błędów w poszczególnych interfejsach API i zapewnia klientom przewidywalną strukturę do przetwarzania.
Pola RFC 7807
Standardowe pola: type (URI identyfikujący problem), title (podsumowanie czytelne dla człowieka), status (kod statusu HTTP), detail (szczegółowe wyjaśnienie), instance (URI konkretnego wystąpienia).
{
"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 w Spring 6
Spring 6 / Spring Boot 3 zawiera wbudowaną obsługę ProblemDetail. Zwracaj ProblemDetail z procedur obsługi wyjątków lub używaj 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;
}Dodawanie własnych rozszerzeń
ProblemDetail obsługuje właściwości rozszerzeń za pomocą setProperty(key, value), co pozwala dodawać szczegóły specyficzne dla domeny, takie jak kody błędów lub błędy pól.
ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
pd.setTitle("Validation Failed");
pd.setProperty("errors", fieldErrors); // custom extension
pd.setProperty("timestamp", Instant.now());Włączanie RFC 7807 dla Spring MVC
Włącz ProblemDetail dla wszystkich wbudowanych wyjątków Spring, ustawiając spring.mvc.problemdetails.enabled=true w pliku application.properties. Spring będzie wtedy automatycznie opakowywać standardowe wyjątki (404, 405 itd.) w format RFC 7807.
# application.properties:
spring.mvc.problemdetails.enabled=trueErrorResponseException
Rzucaj ErrorResponseException z kodu warstwy usług, aby utworzyć odpowiedź RFC 7807 bez metody obsługi — Spring MVC przechwyci ten wyjątek i sformatuje odpowiedź.
throw new ErrorResponseException(HttpStatus.CONFLICT,
ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT,
"Email already exists: " + email), null);Własna podklasa ProblemDetail
Utwórz specyficzną dla domeny podklasę ProblemDetail, aby dodać typowane pola rozszerzeń i zachować przejrzystość kodu procedur obsługi.
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);
}
}Typ zawartości: application/problem+json
Odpowiedzi RFC 7807 powinny używać typu zawartości application/problem+json, aby klienci mogli odróżniać odpowiedzi z problemami od zwykłych danych JSON.
return ResponseEntity.status(HttpStatus.NOT_FOUND)
.contentType(MediaType.APPLICATION_PROBLEM_JSON)
.body(pd);Lista kontrolna spójnej struktury błędów
Dobre API błędów zawiera: (1) identyfikator URI typu czytelny maszynowo, (2) tytuł czytelny dla człowieka, (3) dokładny kod statusu HTTP, (4) szczegółowy komunikat, (5) identyfikator URI wystąpienia żądania, (6) opcjonalne pola rozszerzeń (znacznik czasu, traceId, błędy pól).
Identyfikatory śledzenia na potrzeby obserwowalności
Dodaj identyfikator śledzenia żądania (z Micrometer Tracing lub MDC) jako właściwość rozszerzenia, aby programiści mogli powiązać dzienniki błędów z konkretnym żądaniem, które zakończyło się niepowodzeniem.
pd.setProperty("traceId", MDC.get("traceId"));
pd.setProperty("timestamp", Instant.now());Testowanie szczegółów problemu
W testach @WebMvcTest sprawdzaj, czy typ zawartości odpowiedzi to application/problem+json, a pola JSON, takie jak status, title i detail, mają oczekiwane wartości.
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"));Szybkie sprawdzenie
Która właściwość Spring Boot włącza RFC 7807 dla wbudowanych wyjątków Spring MVC?
Podsumowanie
RFC 7807 standaryzuje odpowiedzi JSON z błędami za pomocą pól type, title, status, detail i instance. Spring 6 udostępnia ProblemDetail oraz ErrorResponseException. Włącz tę funkcję za pomocą spring.mvc.problemdetails.enabled=true. Dodaj traceId i znacznik czasu jako rozszerzenia na potrzeby obserwowalności.
Często zadawane pytania
Czy lekcja „Szczegóły problemu RFC 7807 i spójne odpowiedzi błędów” jest bezpłatna?
Tak — pełny tekst „Szczegóły problemu RFC 7807 i spójne odpowiedzi błędów” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Java Academy, przejdź na CoddyKit PRO. Kurs Java Academy zawiera 4 lekcji w sumie.
Co nauczysz się w „Szczegóły problemu RFC 7807 i spójne odpowiedzi błędów”?
Proszę zwracać ustrukturyzowane dane błędów zgodne z RFC 7807, używając ProblemDetail z Spring 6. Ćwiczysz Java Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć Java Academy?
Nie wymagamy żadnego doświadczenia. Java Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.
Ile czasu zajmuje lekcja „Szczegóły problemu RFC 7807 i spójne odpowiedzi błędów”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji Java Academy?
Tak. Każda lekcja Java Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- Walidacja beanów: @NotNull, @Size, @Pattern
- Niestandardowe adnotacje ograniczeń
- Globalna obsługa wyjątków za pomocą @ControllerAdvice
- Szczegóły problemu RFC 7807 i spójne odpowiedzi błędów