# 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:

1. `title`: Krótki, czytelny opis błędu.
2. `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

1. **Mapowanie wyjątków**: Klasa przechowuje mapę `handlers`, która łączy klasy wyjątków z odpowiednimi handlerami.
2. **Rozwiązywanie handlerów**: Metoda `resolveExceptionHandler` przeszukuje hierarchię klas wyjątku, aby znaleźć najbardziej odpowiedni handler.
3. **Obsługa wyjątków**: Metoda `handleException` znajduje odpowiedni handler i deleguje do niego obsługę wyjątku.

### Dobre praktyki

1. **Hierarchia wyjątków**: Projektuj hierarchię wyjątków tak, aby ułatwić ich mapowanie na odpowiednie handlery.
2. **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`:

1. **Centralne mapowanie**: Rejestr przechowuje mapowanie wszystkich obsługiwanych wyjątków na ich handlery.
2. **Domyślny handler**: Dla każdego nieobsłużonego wyjątku `Exception`, używany jest `DefaultApiExceptionHandler`, który zwraca status HTTP 500 (INTERNAL\_SERVER\_ERROR).
3. **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:

1. Stwórz nowy handler wyjątku, implementujący interfejs `ApiExceptionHandler`.
2. Dodaj nowe mapowanie do statycznej mapy `handlers` w `ApiExceptionHandlerRegistry`:

```
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

1. **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.
2. **Spójność**: Upewnij się, że nowe handlery zwracają odpowiedzi zgodne z `ApiErrorResponse`.
3. **Dokumentacja**: Po dodaniu nowego handlera, zaktualizuj dokumentację API, aby odzwierciedlić nowe możliwe odpowiedzi błędów.
4. **Domyślny handler**: Zawsze pozostaw `DefaultApiExceptionHandler` jako 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.
