_Assistant_Lead_Tech/10_backend_patterns_valides.md

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