Strona może być nieaktualna
Nikt jej nie zmieniał od 26 miesięcy (ostatni commit: 2024-09-11, dem). Jeśli opisuje stan, którego już nie ma, zgłoś ją jako nieaktualną.
Obsługa błędów w API v2¶
Wprowadzenie¶
Niniejsza dokumentacja opisuje sposób obsługi błędów w naszym REST API (v2), zgodnie ze specyfikacją RFC 9457. Wykorzystujemy klasę ApiErrorResponse do strukturyzowania odpowiedzi błędów oraz ApiExceptionHandlerResolver do mapowania i obsługi wyjątków.
Klasa ApiErrorResponse¶
Klasa ApiErrorResponse jest głównym komponentem naszej strategii obsługi błędów. Oto jej główne cechy:
class ApiErrorResponse extends ApiResponse {
private String title
private String detail
String getTitle() { title }
String getDetail() { detail }
void setTitle(String title) { this.title = title }
void setDetail(String detail) { this.detail = detail }
}
Pola¶
status: (Dziedziczone po ApiResponse) Kod statusu HTTP odpowiedzi.title: Krótkie, czytelne dla człowieka podsumowanie błędu.detail: Czytelne dla człowieka wyjaśnienie specyficzne dla tego wystąpienia błędu.
Zgodność z RFC 9457¶
Nasza implementacja ApiErrorResponse jest zgodna ze specyfikacją RFC 9457, która definiuje standardowy format dla odpowiedzi błędów HTTP API. Obecnie skupiamy się na dwóch głównych polach:
title: Krótki, czytelny opis błędu.detail: Szczegółowe wyjaśnienie błędu, specyficzne dla danego wystąpienia.
W przyszłości planujemy rozszerzyć tę implementację o dodatkowe pola wymienione w RFC 9457, takie jak type, instance lub inne niestandardowe elementy.
Obsługa wyjątków¶
Nasza strategia obsługi wyjątków opiera się na klasie ApiExceptionHandlerResolver, która umożliwia mapowanie konkretnych wyjątków na odpowiadające im handlery wyjątków. To podejście pozwala na elastyczną i spójną obsługę różnych typów wyjątków, zachowując jednocześnie ujednoliconą strukturę komunikatów o błędach.
Klasa ApiExceptionHandlerResolver¶
ApiExceptionHandlerResolver jest kluczowym komponentem w naszym systemie obsługi wyjątków:
@CompileStatic
class ApiExceptionHandlerResolver {
Map<Class<? extends Exception>, ApiExceptionHandler> handlers
static ApiExceptionHandlerResolverBuilder builder() {
new ApiExceptionHandlerResolverBuilder()
}
ApiResponse handleException(Exception exception) throws ExceptionHandlerNotFoundException {
ApiExceptionHandler<Exception, ? extends ApiResponse> handler = resolveExceptionHandler(exception.getClass())
return handler.handleException(exception)
}
protected ApiExceptionHandler<Exception, ? extends ApiResponse> resolveExceptionHandler(Class<? extends Exception> exceptionClass) {
// Implementacja metody
}
// Inne metody...
}
Kluczowe funkcje¶
- Mapowanie wyjątków: Klasa przechowuje mapę
handlers, która łączy klasy wyjątków z odpowiednimi handlerami. - Rozwiązywanie handlerów: Metoda
resolveExceptionHandlerprzeszukuje hierarchię klas wyjątku, aby znaleźć najbardziej odpowiedni handler. - Obsługa wyjątków: Metoda
handleExceptionznajduje odpowiedni handler i deleguje do niego obsługę wyjątku.
Dobre praktyki¶
- Hierarchia wyjątków: Projektuj hierarchię wyjątków tak, aby ułatwić ich mapowanie na odpowiednie handlery.
- Spójność: Zapewnij, że wszystkie handlery zwracają odpowiedzi zgodne z
ApiErrorResponse.
ApiExceptionHandlerRegistry¶
Kluczowym elementem obsługi wyjątków dla API v2 jest ApiExceptionHandlerRegistry. Ten rejestr przechowuje mapowania klas wyjątków na odpowiednie handlery.
@CompileStatic
class ApiExceptionHandlerRegistry {
static private final Map<Class<? extends Exception>, ApiExceptionHandler> handlers = [
(WindowsOverlapException): new WindowsOverlapExceptionHandler(),
(Exception) : new DefaultApiExceptionHandler(Exception.class, INTERNAL_SERVER_ERROR)
] as Map<Class<? extends Exception>, ApiExceptionHandler>
static Map<Class<? extends Exception>, ApiExceptionHandler> getHandlers() {
handlers
}
}
Kluczowe cechy ApiExceptionHandlerRegistry:
- Centralne mapowanie: Rejestr przechowuje mapowanie wszystkich obsługiwanych wyjątków na ich handlery.
- Domyślny handler: Dla każdego nieobsłużonego wyjątku
Exception, używany jestDefaultApiExceptionHandler, który zwraca status HTTP 500 (INTERNAL_SERVER_ERROR). - Statyczne mapowanie: Mapowanie jest zdefiniowane jako statyczne pole, co zapewnia szybki dostęp i stałość konfiguracji.
Dodawanie nowych mapowań wyjątków¶
Aby dodać nowe mapowanie dla wyjątku, programista musi zaktualizować rejestr ApiExceptionHandlerRegistry. Oto proces:
- Stwórz nowy handler wyjątku, implementujący interfejs
ApiExceptionHandler. - Dodaj nowe mapowanie do statycznej mapy
handlerswApiExceptionHandlerRegistry:
static private final Map<Class<? extends Exception>, ApiExceptionHandler> handlers = [
// Istniejące mapowania
(WindowsOverlapException): new WindowsOverlapExceptionHandler(),
// Nowe mapowanie
(MyNewException): new MyNewExceptionHandler(),
// Domyślny handler zawsze powinien być na końcu
(Exception): new DefaultApiExceptionHandler(Exception.class, INTERNAL_SERVER_ERROR)
] as Map<Class<? extends Exception>, ApiExceptionHandler>
Dobre praktyki przy rozszerzaniu rejestru¶
- Specyficzność: Dodawaj bardziej specyficzne wyjątki przed ogólnymi. Rejestr jest przeszukiwany w kolejności dodania, więc bardziej specyficzne handlery powinny być wyżej na liście.
- Spójność: Upewnij się, że nowe handlery zwracają odpowiedzi zgodne z
ApiErrorResponse. - Dokumentacja: Po dodaniu nowego handlera, zaktualizuj dokumentację API, aby odzwierciedlić nowe możliwe odpowiedzi błędów.
- Domyślny handler: Zawsze pozostaw
DefaultApiExceptionHandlerjako ostatni w rejestrze, aby zapewnić obsługę nieoczekiwanych wyjątków.
Przykład użycia w kontrolerze/serwisie¶
ApiExceptionHandlerResolver apiExceptionHandlerResolver
try {
// Kod, który może rzucić wyjątek
} catch (Exception e) {
ApiResponse errorResponse = apiExceptionHandlerResolver.handleException(e)
respond(errorResponse, status: errorResponse.status)
}
Przykładowa odpowiedź na błąd WindowsOverlapException¶
```http request HTTP/1.1 422 Vary: Origin Vary: Access-Control-Request-Method Vary: Access-Control-Request-Headers Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Date: Wed, 11 Sep 2024 08:36:17 GMT Keep-Alive: timeout=60 Connection: keep-alive
{ "detail": "We could not place window in warehouse Test Warehouse on ramp R1 with size 120 because it overlaps with another window", "status": 422, "title": "Windows overlaps" } ```
Podsumowanie¶
Połączenie ApiErrorResponse z ApiExceptionHandlerResolver zapewnia:
- Standaryzację odpowiedzi błędów zgodnie z RFC 9457
- Elastyczne mapowanie wyjątków na odpowiednie handlery
- Spójną strukturę komunikatów o błędach w całym API v2
- Łatwość rozszerzania i dostosowywania obsługi błędów do specyficznych potrzeb aplikacji
Konsekwentne stosowanie tego podejścia przyczyni się do tworzenia bardziej niezawodnego, łatwiejszego w utrzymaniu i przyjaznego dla użytkownika API.
Ostatnia zmiana: 2024-09-11 · dem
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e