docs: update README and add Exceptions documentation
Added a section for Exception Management in README and created a new document detailing exception handling and HTTP status codes.
This commit is contained in:
parent
b7c5c98128
commit
b3f02510b5
GPG key ID:
D7EFE2F5CB6CC0E4
2 changed files with 65 additions and 0 deletions
|
|
@ -6,6 +6,7 @@ Arcadia API est une application construite en respectant les principes de la **C
|
|||
|
||||
- [Architecture](#architecture)
|
||||
- [Principes d'implémentation](#principes-dimplémentation)
|
||||
- [Gestion des Exceptions](#gestion-des-exceptions)
|
||||
- [Tests & Assurance Qualité](#tests--assurance-qualité)
|
||||
|
||||
---
|
||||
|
|
@ -28,6 +29,10 @@ L'application est découpée en couches strictes respectant la règle de dépend
|
|||
- **Pattern Presenter** : Les Use Cases (dans `Application`) retournent un `Output` agnostique. La couche `Presentation` utilise ensuite des `Presenters` spécifiques (ex: API) pour transformer cet `Output` en une vue exploitable par l'interface finale (JSON).
|
||||
- **Validation** : La validation stricte du format (ex: HTTP) est gérée dans la couche `Presentation` (via les `FormRequest`). La validation des règles métier est garantie au coeur du `Domain` par les `Value Objects`, qui lèvent des exceptions de type `InvalidArgumentException` traduites en HTTP 422 par le gestionnaire d'erreurs global.
|
||||
|
||||
## Gestion des Exceptions
|
||||
|
||||
Consulter le document [documentation/Exceptions.md](documentation/Exceptions.md) pour la matrice complète de correspondance entre le type d'exception (`DomainException`, `ValidationException`, `NotFoundException`, `ConflictException`) et les codes HTTP RFC 7807 (`400`, `404`, `409`, `422`, `429`, `500`).
|
||||
|
||||
## Tests & Assurance Qualité
|
||||
|
||||
Consulter le document [TEST.md](TEST.md) pour la stratégie de test en pyramide (Unit, Integration, Feature, Arch) et les commandes d'exécution avec couverture de code.
|
||||
|
|
|
|||
60
documentation/Exceptions.md
Normal file
60
documentation/Exceptions.md
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
# 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)
|
||||
|
||||
---
|
||||
|
||||
## 1. Convention REST & RFC 7807
|
||||
|
||||
L'API exprime toutes les réponses d'erreur au format **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: compte déjà supprimé, ressource déjà existante/verrouillée). |
|
||||
| `NotFoundException` | `Domain` / `Application` | **404** | `Resource Not Found` | Ressource introuvable dans le répertoire / BDD. |
|
||||
| `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`).
|
||||
Loading…
Add table
Reference in a new issue