Jérémy Munsch
18fb5f8ac2
Replace not-found exceptions in Arcadia find/show flows with typed outputs (Found*/NotFoundOutput) and map not-found results in presenters/responses while preserving HTTP 404 problem details. Adjust architecture and unit tests to cover concrete output classes, and remove obsolete Arcadia not-found exception classes and their tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
75 lines
4.2 KiB
Markdown
75 lines
4.2 KiB
Markdown
# Gestion des Exceptions & Codes HTTP - Arcadia API
|
|
|
|
Ce document récapitule la stratégie de gestion des exceptions et la correspondance avec les codes de statut HTTP dans **Arcadia API**.
|
|
|
|
---
|
|
|
|
## 📑 Sommaire
|
|
|
|
- [1. Convention REST & RFC 7807](#1-convention-rest--rfc-7807)
|
|
- [2. Matrice de Mapping Exceptions -> Codes HTTP](#2-matrice-de-mapping-exceptions--codes-http)
|
|
- [3. Format de Réponse (Problem Details)](#3-format-de-réponse-problem-details)
|
|
- [4. Distinctions 400 Bad Request vs 422 Unprocessable Content](#4-distinctions-400-bad-request-vs-422-unprocessable-content)
|
|
- [5. Ressources absentes dans les use cases de lecture](#5-ressources-absentes-dans-les-use-cases-de-lecture)
|
|
|
|
---
|
|
|
|
## 1. Convention REST & RFC 7807
|
|
|
|
L'API exprime toutes les réponses d'erreur au format standardisé **RFC 7807 / RFC 9457 Problem Details** avec l'en-tête HTTP :
|
|
`Content-Type: application/problem+json`
|
|
|
|
---
|
|
|
|
## 2. Matrice de Mapping Exceptions -> Codes HTTP
|
|
|
|
| Type d'Exception | Couche Origine | Code HTTP | Titre RFC 7807 | Usage & Description |
|
|
| :----------------------------- | :----------------------- | :-------: | :---------------------- | :------------------------------------------------------------------------------------- |
|
|
| `ValidationException` | `Presentation` | **422** | `Unprocessable Entity` | Échec de validation HTTP (`FormRequest`), champs invalides ou manquants. |
|
|
| `DomainException` | `Domain` | **422** | `Unprocessable Entity` | Violation d'un invariant ou d'une règle métier au cœur du Domaine (ex: `ValueObject`). |
|
|
| `ConflictException` | `Domain` / `Application` | **409** | `Conflict` | Conflit d'état métier (ex: ressource déjà existante ou verrouillée). |
|
|
| `NotFoundException` | `Application` | **404** | `Resource Not Found` | Ressource introuvable considérée comme exceptionnelle. |
|
|
| `NotFoundOutput` (polymorphisme) | `Application` / `Presentation` | **404** | `Resource Not Found` | Ressource absente attendue sur un use case de lecture (pas d'exception levée). |
|
|
| `HttpExceptionInterface` (403) | `Presentation` | **403** | `Forbidden` | Accès refusé par les politiques d'autorisation HTTP. |
|
|
| `ThrottleRequestsException` | `Infra` | **429** | `Too Many Requests` | Dépassement du quota de requêtes API (Rate Limiting). |
|
|
| `Throwable` / `Exception` | Transverse | **500** | `Internal Server Error` | Erreur système non captée (détails masqués hors mode debug). |
|
|
|
|
---
|
|
|
|
## 3. Format de Réponse (Problem Details)
|
|
|
|
Chaque réponse d'erreur retourne une structure JSON standardisée :
|
|
|
|
```json
|
|
{
|
|
"type": "http://localhost/errors/422",
|
|
"title": "Unprocessable Entity",
|
|
"status": 422,
|
|
"detail": "Invalid employee number format",
|
|
"instance": "/api/v1/employees",
|
|
"invalidParams": [
|
|
{
|
|
"name": "domain_invariant",
|
|
"reason": "Invalid employee number format"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Distinctions 400 Bad Request vs 422 Unprocessable Content
|
|
|
|
- **HTTP 400 (Bad Request)** : Réservé aux erreurs de **syntaxe ou de structure HTTP** (ex: JSON illisible, guillemets mal fermés, en-têtes HMAC malformés). Le serveur ne peut pas parser le message.
|
|
- **HTTP 422 (Unprocessable Content)** : Convention **REST & Laravel**. La requête est du JSON syntaxiquement valide, mais son contenu viole les règles de validation HTTP (`FormRequest`) ou les invariants du domaine métier (`DomainException`).
|
|
|
|
---
|
|
|
|
## 5. Ressources absentes dans les use cases de lecture
|
|
|
|
Pour les use cases de consultation (`Find*` / `Show*`), Arcadia API privilégie désormais un retour polymorphique :
|
|
|
|
- `Output` quand la ressource existe
|
|
- `NotFoundOutput` quand la ressource n'existe pas
|
|
|
|
Ce cas n'est pas traité comme une erreur exceptionnelle dans le cœur applicatif ; la couche `Presentation` convertit `NotFoundOutput` en réponse HTTP `404` au format Problem Details.
|