Passer au contenu principal
RM
Retour au blog

Guide complet pour monter un service FastAPI riche (auth, jobs, observabilité) en moins de 7 jours avec Python 3.12.

Radnoumane Mossabely3 min read
Diagramme FastAPI hexagonal
FastAPI
Python
Architecture
Observability
0 vues

Objectif : Démarrer un backend FastAPI opérable (auth + jobs + observabilité) en moins d'une semaine sans sacrifier la maintenabilité.

Synthèse express

  • Angle : Adapter l'architecture hexagonale aux contraintes FastAPI/SaaS.
  • Pain point : APIs bricolées autour des routers, impossible à tester.
  • Promesse : Un socle modulaire + 5 diagrammes PlantUML pour documenter l'équipe.
  • Preuve : Implémenté sur DevMetrics (20k requêtes/jour) + monitoré via OpenTelemetry.
  • CTA : Cloner le blueprint et shipper ton MVP dimanche soir.

Le Problème

Les APIs FastAPI démarrent souvent comme un main.py unique. Trois mois plus tard, les routers contiennent de la logique métier, aucun contrat n'encadre les dépendances et l'onboarding devient douloureux. Résultat : les tests d'intégration sont les seuls garde-fous, et les corrections cassent la prod toutes les deux itérations. Pour un solopreneur ou une petite squad, il faut pourtant garder la vélocité tout en préparant les features sensibles (billing, multi-tenant, jobs). D'où l'intérêt de poser une architecture hexagonale légère : ports/adapters, cas d'usage explicites, et instrumentation par défaut.

La Solution

Étape 1: Cartographier les flux

Diagram 1 Objectif : isoler les responsabilités (contrôleur mince, use case riche, adapters interchangeables).

Points d'attention

  • ⚠️ Ne jamais injecter la session DB directement dans le router.
  • ⚠️ Garder les schémas Pydantic distincts des entités domaine.
  • ✅ Passer par des interfaces (protocols) pour les services externes.

Étape 2: Modulariser les ports/adapters

Diagram 2 Objectif : découpler les cas d'usage des implémentations concrètes.

Comment vérifier

hljs bash
pytest app/usecases/test_register_account.py -q

Attendu : tests unitaires passent sans lancer FastAPI.

Étape 3: Sécuriser le pipeline d'authentification

Diagram 3 Checklist déploiement

  • JWT access (5 min) + refresh (30 min) synchronisés via Redis.
  • Rotation des clés privée/publique (cron quotidien).
  • Règle WAF pour bloquer >5 tentatives/minute.

Étape 4: Observabilité by design

Diagram 4 Actions

  • Ajouter middleware OTLPSpanExporter dans app/main.py.
  • Exposer /metrics (Prometheus) via starlette_exporter.
  • Créer dashboards: temps de réponse, taux d'erreur, jobs RQ.

Étape 5: Déploiement reproductible

Diagram 5 Checklist actionnable

  • Docker multi-stage (api + worker) → images < 200MB
  • GitHub Actions : matrix Python 3.12 + 3.11
  • Secrets gérés via Doppler/1Password CLI

Checklist actionnable

  • Phase Audit (1 jour) : cartographier flux + dettes (router, db, jobs)
  • Phase Build (3 jours) : implémenter ports/adapters + tests use cases
  • Phase Ops (2 jours) : observabilité, CI, déploiement blue/green

Temps total estimé : 6 jours focus.

Conclusion

  1. FastAPI peut supporter des SLA exigeants si l'architecture est préparée.
  2. Un use case explicite vaut mieux que 10 routers magiques.
  3. Instrumenter tôt réduit le stress lors du premier incident.

Call to Action : Cloner le blueprint, brancher OpenTelemetry et publier un postmortem même sans incident ✨

Partager: