Fullstack Patterns — Architecture backend solide

Patterns éprouvés pour tout projet backend ou fullstack. Se charge automatiquement quand du code touche des routes, controllers, services, base de données, auth ou API.

Architecture 3 couches

Controller (HTTP) → Service (Business) → Repository (Data Access)

Couche	Fait	Jamais
Controller	Parse request, valide input, appelle service, formate réponse	Business logic, requêtes DB
Service	Règles métier, orchestration, transactions	Types HTTP, accès DB direct
Repository	Requêtes DB, appels API externes	Business logic, types HTTP

Organiser par feature, pas par couche technique. orders/ contient controller + service + repository + tests, pas controllers/, services/, repositories/.

7 règles de fer

1. Controllers minces — délèguent aux services, jamais de logique métier
2. Services isolés du HTTP — jamais d'import de types Request/Response
3. Config par variables d'env — validées au démarrage, fail fast
4. Erreurs typées — chaque erreur a un type, un log, un format de réponse cohérent
5. Validation aux frontières — tout input validé à l'entrée (Zod, Joi, Pydantic)
6. Logging structuré JSON — avec request ID propagé par middleware
7. Injection de dépendances — constructeur, jamais d'instanciation dans les services

Ordre des middlewares

RequestID → Logging → CORS → RateLimit → BodyParse → Auth → Authz
→ Validation → Handler → ErrorHandler → Response

API REST — Conventions

Nommage

• URLs : noms pluriels, kebab-case → /order-items, pas /getOrderItems
• JSON : camelCase → firstName
• Headers : Train-Case → X-Request-Id
• Max 2 niveaux de nesting → /orders/123/items. Au-delà : query params → GET /reviews?orderId=123

Status codes

Code	Quand
200	GET/PATCH/PUT success
201	POST avec Location header
204	DELETE sans contenu
400	Parse failure
401	Auth manquant
403	Permission refusée
404	Ressource introuvable
409	Conflit (doublon)
422	Validation échouée
429	Rate limit

Error envelope (RFC 9457)

{
  "type": "https://api.example.com/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "Account balance $10.00 < withdrawal $50.00",
  "request_id": "req_7f3a8b2c"
}

Toutes les erreurs suivent ce format. Request ID toujours inclus.

Pagination

Cursor (préféré pour gros datasets) : retourne next_cursor + has_more Offset : pour datasets stables et petits

• Default : 20 items, max : 100
• Filtres : ?status=shipped, ?price_gte=10&price_lte=100
• Tri : ?sort=-created_at (- = descendant)
• Champs : ?fields=id,name

Authentification

Token pattern

• Access token court (15min) + refresh token server-side
• Stockage : mémoire + cookie httpOnly pour refresh — jamais localStorage (XSS)
• Claims minimaux : userId + roles, pas l'objet user entier
• Credentials dans header Authorization: Bearer {token} — jamais en query param (visible dans les logs)

Refresh flow

Requête → 401 → intercepteur attrape → POST /api/auth/refresh (credentials: include)
→ nouveau token → retry requête originale (transparent pour l'UI)

CORS

• Origins explicites en production — jamais * avec credentials
• Frontend : credentials: 'include' pour envoyer les cookies cross-domain

Base de données

Schema design

• IDs : UUID pour les IDs publics (API), serial pour les clés internes (joins) — hybride sécurité + performance
• Normalisation : commencer en 3NF, dénormaliser seulement avec preuves mesurées de problème de perf
• Migrations : toujours réversibles, jamais de SQL manuel

Indexing

• Composite index = leftmost prefix : (A, B, C) sert A et A+B, pas B seul
• Toujours indexer les foreign keys
• Index partiels pour les sous-ensembles (ex: seulement les enregistrements actifs)
• Multi-tenant : tenant_id dans chaque table, leftmost dans composite index

Connection pooling

Pool size de départ : (CPU cores x 2) + nombre de disques

Real-time — Arbre de décision

Besoin	Solution
Server → Client uniquement	SSE (le plus simple, passe les proxies)
Bidirectionnel	WebSocket (heartbeat + reconnection obligatoires)
Polling simple	React Query refetchInterval (pas d'infra)

File upload — Arbre de décision

Taille	Solution
> 5MB	Presigned URL → upload direct S3 → sauver la référence (zéro charge serveur)
< 5MB	Multipart form → stream through server

Error handling

Pattern

// Créer des erreurs typées par domaine
class NotFoundError extends AppError { status = 404 }
class ValidationError extends AppError { status = 422 }

// Global middleware attrape tout
app.use((err, req, res, next) => {
  if (err instanceof AppError) {
    // Opérationnel → réponse structurée
    return res.status(err.status).json(err.toRFC9457())
  }
  // Inattendu → log + 500 générique
  logger.error({ err, requestId: req.id })
  res.status(500).json({ title: 'Internal Server Error', request_id: req.id })
})

• Erreurs opérationnelles (attendues) → réponse structurée avec status code
• Erreurs de programmation (inattendues) → log + 500 générique au client
• Jamais de stack traces au frontend
• Jamais de retry sur 4xx (l'erreur client ne changera pas) — retry uniquement sur 5xx

Anti-patterns

Ne pas faire	Faire
Business logic dans les controllers	Service layer
process.env partout	Config centralisée typée
Erreurs génériques	Hiérarchie d'erreurs typées
DB direct dans controllers	Repository pattern
Pas de validation	Zod/Pydantic à la frontière
console.log	Logger JSON structuré
URL API hardcodée	Variable d'environnement
JWT dans localStorage	Memory + cookie httpOnly
Erreurs API brutes au client	Messages human-readable
Skip loading states	Skeleton/spinner

Production hardening checklist

• Health check endpoints (/health liveness, /ready readiness)
• Graceful shutdown (SIGTERM → drain connections, close DB)
• CORS : origins explicites, jamais *
• Security headers (helmet ou équivalent)
• Rate limiting sur les endpoints publics
• Validation sur TOUS les endpoints
• HTTPS forcé
• Erreurs internes jamais exposées au client

Tool Boundaries

• Appliquer ces patterns dans le stack existant du projet
• Ne pas migrer de framework ou d'ORM sauf demande explicite
• Ne pas restructurer un projet entier — améliorer ce qui est touché