Update 25_01_26

10_backend_patterns_valides.md

@@ -0,0 +1,318 @@
+# Patterns back-end validés
+
+Ce fichier contient **uniquement** des patterns back-end :
+
+- testés,
+- validés,
+- utilisés en conditions réelles.
+
+Objectif : éviter de réinventer la roue et réduire le temps de debug.
+
+Dernière mise à jour : 25-01-2026
+
+---
+
+## Règle d’or
+
+Si ce n’est pas confirmé comme fonctionnel et utile, **ça n’a rien à faire ici**.
+
+- Pas de “bonnes pratiques” vagues
+- Pas de dépendances implicites à une stack
+- Si c’est spécifique à un framework / runtime / DB : on le note
+
+---
+
+## Périmètre couvert
+
+- API (REST/GraphQL), services applicatifs
+- authn/authz
+- contrats (validation / schémas)
+- gestion d’erreurs
+- DB & migrations
+- observabilité
+- opérations sensibles (idempotence, retries)
+- intégrations (webhooks, jobs async)
+
+---
+
+## Format standard d’un pattern
+
+## Pattern : <Nom clair>
+
+- Objectif : …
+- Contexte : …
+- Quand l’utiliser : …
+- Quand l’éviter : …
+- Avantage : …
+- Limites / vigilance : …
+- Validé le : DD-MM-YYYY
+- Contexte technique : (obligatoire) ex. `Node 20 / Postgres 16` ou `Python 3.12 / FastAPI / Redis`
+
+### Implémentation (exemple minimal)
+
+```txt
+(contenu)
+```
+
+### Checklist (si pertinente)
+
+- Erreurs standardisées
+- Validation d’entrée (schéma)
+- Observabilité minimale (requestId/traceId + logs)
+- Sécurité (authn/authz + secrets)
+- Tests au bon niveau
+- Idempotence si opération sensible
+
+---
+
+## Pattern : Format d’erreur API standardisé
+
+- Objectif : fournir des erreurs prévisibles, exploitables et cohérentes pour tous les clients.
+- Contexte : API consommée par front-end, automatisations ou intégrations externes.
+- Quand l’utiliser : dès qu’une API est exposée à autre chose qu’un usage interne trivial.
+- Quand l’éviter : jamais.
+- Avantage :
+  - Debug plus rapide
+  - UX maîtrisée côté client
+  - Observabilité améliorée
+- Limites / vigilance :
+  - Discipline requise pour éviter les formats ad hoc
+- Validé le : 25-01-2026
+- Contexte technique : API HTTP agnostique
+
+### Implémentation (exemple minimal)
+
+```json
+{
+  "error": {
+    "code": "USER_NOT_FOUND",
+    "message": "Utilisateur introuvable",
+    "requestId": "abc-123"
+  }
+}
+```
+
+### Checklist
+
+- Codes HTTP cohérents (4xx / 5xx)
+- Codes d’erreur applicatifs stables
+- Message utilisateur non technique
+- requestId présent
+
+---
+
+## Pattern : Middleware de corrélation (requestId / traceId)
+
+- Objectif : relier chaque requête aux logs et erreurs associées.
+- Contexte : toute API ou service exposé.
+- Quand l’utiliser : systématiquement en production.
+- Quand l’éviter : jamais.
+- Avantage :
+  - MTTR réduit drastiquement
+  - Debug cross-services possible
+- Limites / vigilance :
+  - Doit être propagé partout (logs, erreurs, appels sortants)
+- Validé le : 25-01-2026
+- Contexte technique : Backend agnostique (HTTP)
+
+### Implémentation (exemple minimal)
+
+```txt
+- Générer un requestId à l’entrée si absent
+- Le propager dans le contexte de requête
+- L’inclure dans chaque log et réponse d’erreur
+```
+
+### Checklist
+
+- requestId généré ou repris d’un header existant
+- Présent dans tous les logs
+- Présent dans les erreurs retournées
+
+---
+
+## Pattern : Idempotency key pour opérations sensibles
+
+- Objectif : empêcher les doublons lors de retries ou timeouts.
+- Contexte : création de ressources, paiements, webhooks.
+- Quand l’utiliser : toute opération non strictement en lecture.
+- Quand l’éviter : endpoints purement GET.
+- Avantage :
+  - Protection contre doublons
+  - Robustesse face aux retries
+- Limites / vigilance :
+  - Stockage et expiration des clés à gérer
+- Validé le : 25-01-2026
+- Contexte technique : API HTTP + DB transactionnelle
+
+### Implémentation (exemple minimal)
+
+```txt
+- Client fournit Idempotency-Key
+- Backend stocke la clé + résultat
+- Retry retourne le résultat initial
+```
+
+### Checklist
+
+- Clé obligatoire sur endpoints sensibles
+- Contrainte d’unicité côté DB
+- Comportement documenté
+
+---
+
+## Pattern : Pagination robuste (cursor-based) pour les listings
+
+- Objectif : fournir des listings stables et performants sans incohérences entre pages.
+- Contexte : endpoints de liste (ex. /users, /orders) avec volume potentiellement important.
+- Quand l’utiliser : dès qu’un listing peut dépasser quelques dizaines/centaines d’items ou subir des écritures concurrentes.
+- Quand l’éviter : listes strictement petites et statiques.
+- Avantage :
+  - Résultats stables malgré insertions/suppressions
+  - Meilleure performance que l’offset sur gros volumes
+  - Expérience client plus fiable
+- Limites / vigilance :
+  - Nécessite un tri déterministe (champ + tie-breaker)
+  - Complexité légèrement supérieure à offset/limit
+- Validé le : 25-01-2026
+- Contexte technique : API HTTP + DB (Postgres/MySQL), agnostique framework
+
+### Implémentation (exemple minimal)
+
+```txt
+- Trier par (createdAt DESC, id DESC) (exemple)
+- Le client envoie cursor = dernier (createdAt,id) reçu
+- Le backend renvoie nextCursor si plus de résultats
+- Ne jamais exposer de cursor implicite ou non documenté
+```
+
+### Checklist
+
+- Tri déterministe (avec tie-breaker)
+- nextCursor renvoyé et documenté
+- Limite max de page (protection)
+- Index DB aligné avec le tri
+
+---
+
+## Pattern : Exécution asynchrone des tâches longues (queue + outbox light)
+
+- Objectif : sortir les opérations longues ou fragiles du chemin request/response.
+- Contexte : envoi d’emails, appels SaaS, génération de PDF, traitements batch, webhooks sortants.
+- Quand l’utiliser : dès qu’une opération peut dépasser la latence acceptable ou dépendre d’un service externe.
+- Quand l’éviter : opérations réellement instantanées et sans dépendances externes.
+- Avantage :
+  - API plus rapide et plus fiable
+  - Retries maîtrisés
+  - Meilleure résilience aux pannes externes
+- Limites / vigilance :
+  - Demande une discipline stricte sur l’idempotence
+  - Nécessite une stratégie minimale de dead-letter ou d’alerting
+- Validé le : 25-01-2026
+- Contexte technique : Backend agnostique + DB transactionnelle + worker
+
+### Implémentation (exemple minimal)
+
+```txt
+- API écrit un job ou event en DB dans la transaction métier
+- Worker lit les jobs en attente et exécute
+- Retries avec backoff + compteur
+- Statut FAILED ou dead-letter + alerte
+- Idempotence par clé métier ou idempotency key
+```
+
+### Checklist
+
+- Job créé dans une transaction (évite les pertes)
+- Retries et backoff définis
+- Dead-letter ou statut FAILED visible
+- Idempotence garantie
+- Logs corrélés (requestId/traceId)
+
+---
+
+## Pattern : Soft delete et archivage explicite
+
+- Objectif : permettre la suppression logique sans perte immédiate de données.
+- Contexte : données métier critiques, besoins d’audit, restauration ou conformité.
+- Quand l’utiliser : dès qu’une suppression peut avoir des impacts métier ou légaux.
+- Quand l’éviter : données purement techniques ou réellement éphémères.
+- Avantage :
+  - Restauration possible
+  - Audit et traçabilité
+  - Réduction des suppressions irréversibles
+- Limites / vigilance :
+  - Complexité accrue sur les requêtes
+  - Nécessite une discipline stricte (filtres par défaut)
+- Validé le : 25-01-2026
+- Contexte technique : API + DB relationnelle
+
+### Implémentation (exemple minimal)
+
+```txt
+- Champ deletedAt (nullable) ou status
+- Les requêtes standards filtrent deletedAt IS NULL
+- Endpoints dédiés pour restauration / purge
+- Index DB tenant compte du soft delete
+```
+
+### Checklist
+
+- Filtrage soft delete par défaut
+- Restauration explicite possible
+- Purge maîtrisée (cron / job)
+- Index DB adaptés
+- Tests sur cas supprimé / restauré
+
+---
+
+## Pattern : Webhooks sortants robustes et idempotents
+
+- Objectif : garantir des intégrations fiables avec des systèmes externes.
+- Contexte : notifications, synchronisations, événements métier sortants.
+- Quand l’utiliser : dès qu’un événement doit être transmis à un tiers.
+- Quand l’éviter : intégrations strictement synchrones et internes.
+- Avantage :
+  - Tolérance aux pannes réseau
+  - Retries maîtrisés
+  - Observabilité des échecs
+- Limites / vigilance :
+  - Gestion des retries et du volume
+  - Nécessite une idempotence côté consommateur
+- Validé le : 25-01-2026
+- Contexte technique : Backend + HTTP + worker/queue
+
+### Implémentation (exemple minimal)
+
+```txt
+- Événement persisté (outbox) en DB
+- Envoi asynchrone via worker
+- Retries avec backoff
+- Signature du payload (HMAC)
+- Idempotency key dans le header
+```
+
+### Checklist
+
+- Payload signé et vérifiable
+- Retries + backoff définis
+- Dead-letter ou statut FAILED visible
+- Idempotence documentée
+- Logs corrélés (requestId/traceId)
+
+### Index (à remplir au fil des validations)
+
+- Format d’erreur API standardisé
+- Middleware de corrélation (requestId / traceId)
+- Idempotency key pour opérations sensibles
+- Pagination robuste (cursor-based) pour les listings
+- Exécution asynchrone des tâches longues (queue + outbox light)
+- Soft delete et archivage explicite
+- Webhooks sortants robustes et idempotents
+
+⸻
+
+### Notes importantes
+
+- On préfère 5 patterns solides à 50 “bons conseils”.
+- Un pattern = une idée actionnable + son cadre d’utilisation.