La version anglaise disponible sur DevTo : The Django Digestive System: A request journey in a Django app instance.

Avant de débuter, faisons un bref passage sur quelques mots qu'on va utiliser tout au long de l'article

Socket : ([Ref 1])

Un socket, c'est un point de connexion entre deux machines sur un réseau. Une sorte de tuyau par lequel les données circulent. Quand un navigateur envoie une requête, il ouvre une connexion socket vers notre serveur. Quand le serveur répond, il renvoie des octets par ce même socket.

TCP, HTTP : ([Ref 2])

TCP (Transmission Control Protocol) est la couche transport. Elle définit les règles d'acheminement fiable des données entre machines. HTTP tourne au-dessus de TCP. HTTP, c'est simplement du texte, formaté d'une façon précise. Un navigateur envoie un message HTTP via une connexion TCP vers notre serveur.

WSGI (Web Server Gateway Interface) : ([Ref 3])

WSGI est l'interface standard entre une application web Python et un serveur web. Un serveur WSGI (Gunicorn, uWSGI, etc.) se place entre internet et Django : il accepte la connexion TCP, lit les octets HTTP bruts, et appelle Django avec un dictionnaire Python standardisé appelé environ ([Ref 4]) : ce dictionnaire contient tout ce qui concerne la requête entrante : méthode, chemin, headers, corps. Django ne touche jamais TCP ni le socket brut directement. C'est le rôle du WSGI.

Middleware : ([Ref 5])

Le middleware existe dans tous les frameworks web sérieux : Express, NestJS, Laravel, Rails, etc. Dans Django, c'est une couche qui se place entre le serveur WSGI et la vue (qui contient notre code de traitement de la requête). Un middleware peut lire, modifier, ou stopper une requête entièrement, en retournant une réponse directement sans aller plus loin. On appelle ça un court-circuit.

ORM : ([Ref 6])

ORM signifie Object-Relational Mapper. C'est la couche qui traduit entre objets Python et tables de base de données. Rails l'appelle ActiveRecord, Laravel l'appelle Eloquent : dans Django, c'est simplement « l'ORM ».

Toujours là ? Bien. 👌 Tout ça dit, traçons le chemin d'une requête. 🗺️

1. Avant Django : des octets sur un fil, que dis-je: sur le socket.

Un navigateur décide d'appeler notre API. Il ouvre une connexion socket [Ref 1] vers notre serveur et envoie quelque chose comme ça le format texte typique d'une requête HTTP :

GET /users/42/ HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbG...
Accept: application/json
...
...
...

C'est tout. Du texte brut. Pour l'instant, pas de Python, pas de Django, pas d'objets. Une chaîne formatée qui voyage dans le socket [Ref 1], contrôlée par le standard TCP [Ref 2].

Le serveur WSGI [Ref 3] reçoit ça sur le socket, parse le texte HTTP, et construit le dictionnaire environ [Ref 4]. Ensuite il appelle Django. C'est là que notre histoire commence vraiment.

2. La naissance de HttpRequest

Le point d'entrée de chaque requête Django, c'est WSGIHandler.__call__(), défini dans django/core/handlers/wsgi.py.

C'est la ligne exacte où la requête cesse d'être un dictionnaire pour devenir un objet Python :

# django/core/handlers/wsgi.py (simplifié)
class WSGIHandler(base.BaseHandler):
    def __call__(self, environ, start_response):
        request = self.request_class(environ)  # ← naissance ici
        response = self.get_response(request)
        # ...

self.request_class, c'est la classe HttpRequest. Django prend le dictionnaire environ brut et l'emballe dans un objet Python riche et utilisable.

Voici à quoi ressemble cette transformation :

L'attribut request.META contient toujours le dictionnaire environ complet. Tout est simplement accessible via une interface Python propre et utilisable dans les vues.

On suit toujours ? Bien 👌. L'objet HttpRequest est là. Maintenant, il doit continuer la traversée.

3. Le flux des middlewares [Ref 5]

C'est là où beaucoup de développeurs ont un modèle mental flou, et ça vaut la peine de clarifier.

Le flux des middlewares n'est pas un pipeline où chaque étape traite la requête indépendamment puis la passe au suivant. C'est une pile d'enveloppes imbriquées. Chaque middleware enveloppe tout ce qui vient après lui.

Voici à quoi ressemble un middleware concrètement :

class ExempleMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response  # la couche suivante

    def __call__(self, request):
        # → s'exécute AVANT la vue
        faire_quelque_chose_avec(request)

        response = self.get_response(request)  # appelle la couche suivante.
        # Si on a n autres couches avant la vue,
        # toutes s'exécutent, et la vue aussi,
        # avant qu'on continue à l'instruction suivante ici.

        # ← s'exécute APRÈS la vue, sur le chemin du retour
        faire_quelque_chose_avec(response)

        return response

Les middlewares sont chaînés. self.get_response, c'est le middleware suivant dans la chaîne (ou la vue elle-même si on est au dernier middleware). L'appeler envoie la requête plus loin. Ne pas l'appeler et retourner une réponse directement, c'est un court-circuit: la vue ne tourne jamais.

Django traite MIDDLEWARE de haut en bas à l'aller, de bas en haut au retour. L'ordre n'est pas optionnel.

Voici ce que les middlewares intégrés injectent pendant le voyage de la requête :

Comparé au système digestif humain, c'est le tube intestinal de la requête. Chaque couche absorbe/ajoute une chose, un attribut: session, identité utilisateur etc. et passe le reste. Au moment où la requête ressort, elle est complètement enrichie. Un court-circuit ? C'est le corps qui rejette quelque chose avant qu'elle atteigne la circulation sanguine.

Quand la requête arrive à notre vue (officiellement la circulation sanguine 😅), les attributs request.session et request.user sont déjà là, ajoutés par les middlewares correspondants. Pas de magie, juste le flux des middlewares qui fait son travail silencieusement.

4. Le routage URL : le carrefour

L'objet HttpRequest ayant traversé la pile des middlewares, Django doit maintenant déterminer quelle vue doit la traiter.

URLResolver (chargé de déterminer les vues associées aux urls) parcourt urlpatterns (la liste qu'on définit dans urls.py du dossier de config), en comparant le chemin de la requête à chaque pattern. Le premier match est utilisé. Les patterns matchés deviennent des kwargs.

# urls.py
path("users/<int:pk>/", UserDetailView.as_view()),

# requête vers /users/42/ → kwargs = {"pk": 42}

Si rien ne correspond, Django retourne un 404 avant que notre code de vue tourne. À cette étape : pas de vue, pas de sérializer, pas de base de données. Juste un 404.

On y est presque. C'est ici que notre code s'exécute vraiment.

5. Notre code s'exécute enfin 💻

La vue reçoit deux choses : l'objet HttpRequest et les kwargs résolus. Tout ce qui s'est passé avant (socket, WSGI, environ, middlewares, routage) c'était la machinerie de Django. Cette partie-là, c'est la nôtre.

class UserDetailView(RetrieveAPIView):
    def get(self, request, pk):
        # request.user est déjà défini (merci AuthenticationMiddleware)
        # pk vient de l'URL (merci URLResolver)
        user = User.objects.get(pk=pk)
        return Response(UserSerializer(user).data)

User.objects.get(pk=pk) : c'est là que l'ORM [Ref 6] entre en jeu. Django traduit cet appel Python en requête SQL, interroge la base de données, et retourne un objet Python. Une ligne de notre côté, beaucoup de choses sous le capot. [J'ai essayé de lire ce code dans le module django une fois. Ce n'est pas une logique simple. Merci aux contributeurs Django.]

Pour ceux qui utilisent Django REST Framework : APIView.dispatch() (la base des ViewSets, etc.) ajoute une couche d'exécution supplémentaire avant que notre .get(), .post(), .create() ou action personnalisée tourne : classes d'authentification, classes de permissions, classes de throttling. On fera un article dédié là-dessus. Pour l'instant, sachez juste que c'est là.

6. Le voyage de retour

Notre vue retourne un objet HttpResponse. C'est là que la pile de middlewares se déroule.

La même chaîne tourne dans le sens inverse : de bas en haut. La logique post-vue de chaque middleware s'exécute au fur et à mesure que get_response(request) remonte la pile d'appels.

Des headers comme Content-Security-Policy, Strict-Transport-Security et Set-Cookie sont ajoutés pendant ce voyage retour. Le middleware en haut de MIDDLEWARE est le dernier à toucher la réponse. C'est l'imbrication en action.

7. Et ça ressort

WSGIHandler prend l'objet HttpResponse retourné et le reconvertit en octets selon le protocole HTTP.

Le client reçoit du texte HTTP :

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 87
Set-Cookie: sessionid=abc123; HttpOnly; Path=/
...
...
...

{"id": 42, "name": "..."}

Boucle bouclée. Des octets en entrée, des octets en sortie. Tout ce qui s'est passé entre les deux, c'était Django. Digestion terminée.

C'est le voyage complet

La plupart d'entre nous restons simplement dans la section 5. La vue, le sérializer, la logique métier. C'est là que vit le produit c'est normal.

Mais la prochaine fois que le retour de request.user est un AnonymousUser inattendu, qu'un header de réponse manque, ou qu'un 404 apparaît avant même que notre code ait la moindre chance de tourner, on sait exactement quelle couche regarder.

Ce flow n'est pas de la magie. Ce sont des couches, chacune faisant une chose, dans un ordre précis. Comprendre ça aide aussi à personnaliser certains comportements quand notre logique métier l'exige.

Dans quelle couche avez-vous dû creuser une fois lors d'un débogage ? Dites-le en commentaire.

Si vous repérez quelque chose d'incorrect, ou si vous faites différemment avec de meilleurs résultats, commentez. Je suis là pour apprendre autant que pour partager. 🤝

Il y a quelques semaines, un développeur Django senior a rejoint un projet que je construisais. Après avoir parcouru le code, il m'a envoyé ce message :

« Il y a pas mal de choses pas bien finies. Des lacunes. Mais il y a aussi de très belles choses qui m'ont permis d'avancer vite. »

C'est cette dernière phrase qui m'a donné envie d'écrire : pour garder une trace de ce qui a fonctionné, et pour échanger avec d'autres. Alors me voilà. 👋

Bien structurer un projet, surtout un grand, c'est crucial. C'est prendre des décisions tôt qui permettent de naviguer avec confiance, d'ajouter des features sereinement, et de passer la main sans être rappelé toutes les cinq minutes.

Spoil alert: C'est mon premier article technique. D'autres suivront sur Django, l'architecture, et les choses apprises au fil des projets. Les discussions et commentaires sont les bienvenus.

On y va. 🚀

Le problème avec la structure par défaut de Django

Quand tu lances django-admin startproject backend, tu obtiens ça :

backend/
├── backend/
│   ├── settings.py
│   ├── urls.py
│   ├── wsgi.py
│   └── asgi.py
├── manage.py

Tu ajoutes ta première app :

python manage.py startapp myapp

Et soudain :

backend/
├── myapp/
│   ├── models.py
│   ├── views.py
│   ├── admin.py
│   └── tests.py
├── backend/
│   └── settings.py

Ça marche parfaitement. Pour un tutoriel. 😬

En contexte de production réel, models.py dépasse rapidement les 1 000 lignes. views.py devient illisible. settings.py mélange config base de données, email, AWS, et tout le reste.

Pour qu'une app puisse scaler correctement, il devient naturel de designer sa structure dès le départ.

1. Le découpage racine : apps/ et backend/

La décision la plus impactante : séparer tes apps Django de la configuration du projet.

mon-projet/
├── backend/           ← Config du projet Django (settings, urls, celery…)
├── apps/              ← Toutes tes apps Django
├── docs/              ← Documentation
├── scripts/           ← Scripts utilitaires
├── tests/             ← Suite de tests
├── manage.py
└── requirements.txt

N'importe quel développeur qui ouvre ce dépôt comprend immédiatement la carte :

• backend/ → config du framework, on ne touche pas sans raison

• apps/ → ici vivent les features et la logique métier

Simple, évident, sans ambiguïté. C'est l'objectif.

2. Le dossier backend/ : une config qui respire

L'erreur la plus courante dans backend/ : garder un settings.py monolithique. JWT, email, AWS, rate limiting : tout dans un seul fichier, ça devient vite ingérable.

Découpe les settings par domaine :

backend/
├── settings/
│   ├── __init__.py      ← Charge les sous-modules
│   ├── base.py          ← Config Django principale (installed apps, middleware, DB…)
│   ├── smtp.py          ← Config email uniquement
│   └── configs/
│       └── storages.py  ← Config S3/stockage média
├── urls.py
├── celery.py
├── asgi.py
└── wsgi.py

# backend/settings/smtp.py : uniquement la config email
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = os.environ.get("EMAIL_HOST")
EMAIL_PORT = int(os.environ.get("EMAIL_PORT", 587))
EMAIL_USE_TLS = True

# backend/settings/configs/storages.py : uniquement le stockage
DEFAULT_FILE_STORAGE = "storages.backends.s3boto3.S3Boto3Storage"
AWS_STORAGE_BUCKET_NAME = os.environ.get("AWS_BUCKET_NAME")

Quand un dev DevOps doit mettre à jour la config email, il va directement dans smtp.py. Il n'a pas à lire 400 lignes de settings sans rapport. C'est du respect pour le temps du prochain développeur. 🙏

3. Le dossier apps/ : un domaine, une app

Chaque domaine fonctionnel a sa propre app Django. Pas de core/ monolithique qui contient tout et n'importe quoi.

apps/
├── authentication/    ← Inscription, connexion, JWT…
├── transactions/      ← Transactions, remboursements…
├── users/             ← Modèle utilisateur, profils…
├── notifications/     ← Email, SMS, Push, WhatsApp…
├── marketing/         ← Parrainage, messages de contact…
├── settings/          ← Paramètres système et utilisateur
└── utils/             ← Code partagé (modèle de base, enums, erreurs, middleware)

Chaque app est un contexte délimité : elle possède ses modèles, ses vues, ses serializers, sa logique métier. Si demain tu extrais notifications/ en microservice, les frontières sont déjà tracées.

La règle que j'applique : si tu peux le décrire par un nom de domaine, c'est une app. Authentication, Transactions, Notifications. Pas Stuff, pas Core, pas Api.

4. À l'intérieur d'une app : chaque fichier a un rôle

Les models.py / views.py monolithiques générés par défaut ne facilitent pas le scaling. Voici à quoi ressemble une app bien structurée :

apps/transactions/
├── models/
│   ├── __init__.py          ← Star-imports de tous les fichiers modèles
│   ├── transactions.py
│   ├── refunds.py
│   └── …
├── serializers/
│   ├── transactions.py
│   └── refunds.py
├── views/
│   ├── transactions.py
│   └── refunds.py
├── services/
│   ├── transaction_processor.py
│   └── refund_service.py
├── admin/
│   └── transactions.py
├── router.py
├── urls.py
├── tasks.py
├── apps.py
└── tests.py

Découper les modèles en sous-fichiers

Le models/__init__.py ré-exporte tout via des star imports :

# apps/transactions/models/__init__.py
from apps.transactions.models.transactions import *
from apps.transactions.models.refunds import *

Du point de vue de Django, rien ne change : apps.transactions.Transaction fonctionne toujours. Du point de vue du développeur, tout change :

• Chaque fichier modèle reste lisible (< 300 lignes)

• Les conflits Git sont rares et simples à résoudre

• Chercher "transactions" dans tes fichiers remonte modèles, services et serializers d'un coup

La couche services/

Les vues ne doivent pas contenir de logique métier. Ce n'est pas une règle que j'ai inventée: c'est un principe qui sauve à chaque fois qu' on dois réutiliser de la logique dans une tâche, une commande de management, ou un test.

# ❌ Logique métier dans la vue antipattern classique
class TransactionViewSet(ModelViewSet):
    def create(self, request):
        dest_user = User.objects.get(...)
        if not dest_user.is_active:
            raise ValidationError("Utilisateur indisponible")
        # ...50 autres lignes de logique métier...

# ✅ La vue délègue à un service
class TransactionViewSet(ModelViewSet):
    def create(self, request):
        serializer = CreateTransactionSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        transaction = TransactionProcessor.create_transaction(
            user=request.user,
            **serializer.validated_data
        )
        return Response(TransactionSerializer(transaction).data)

TransactionProcessor.create_transaction() peut maintenant être appelé depuis une vue, une tâche, un test, ou une commande de management sans changer une seule ligne. 💪

5. Le modèle de base : la fondation de chaque table

Chaque modèle du projet hérite d'une seule classe. Une seule.

# apps/utils/models/base_model.py
from uuid import uuid4
from django.db import models
from django_softdelete.models import SoftDeleteModel

class AbstractCommonBaseModel(SoftDeleteModel):
    uuid = models.UUIDField(primary_key=True, default=uuid4, editable=False)
    active = models.BooleanField(default=True)
    timestamp = models.DateTimeField(auto_now_add=True)
    updated = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True

Chaque modèle l'utilise :

from apps.utils.models.base_model import AbstractCommonBaseModel

class Transaction(AbstractCommonBaseModel):
    # uuid, active, timestamp, updated → déjà là, gratuitement
    status = models.CharField(...)
    amount = models.DecimalField(...)

Du DRY pur. Tu obtiens gratuitement, sur chaque table :

La suppression douce est devenue un réflexe. On ne supprime jamais définitivement un enregistrement sensible. Même si un utilisateur "supprime" quelque chose depuis son interface, la ligne reste pour les audits, les litiges, la réconciliation. 🔍

Le définir dans le modèle de base signifie qu'on ne peut pas l'oublier. Le pattern est imposé au niveau de la hiérarchie de classes.

6. L'app utils/ : la bibliothèque interne du projet

Chaque projet accumule du code partagé. La question est : vit-il éparpillé partout, ou dans un endroit dédié ?

apps/utils/
├── models/
│   └── base_model.py
├── xlib/
│   ├── enums/
│   │   ├── base.py
│   │   ├── errors.py
│   │   ├── transactions.py
│   │   └── users.py
│   ├── error_util.py
│   ├── exceptions.py
│   └── validators.py
├── middleware/
└── commons/
    └── mixins.py

Un pattern à souligner : le système d'enums. Plutôt que de disperser des tuples de choix verbeux à travers les fichiers modèles :

# ❌ L'ancienne façon, répétée partout
status = models.CharField(choices=[('PENDING', 'En attente'), ('FAILED', 'Échoué'), ...])

# ✅ Un enum, réutilisé partout
from apps.utils.xlib.enums import TransactionStatusEnum

status = models.CharField(
    choices=TransactionStatusEnum.items(),
    default=TransactionStatusEnum.PENDING.value,
)

Une source de vérité. Zéro copier-coller, zéro drift. 🎯

7. Le routage URL : trois couches, des contrats clairs

Chaque app suit le même pattern URL en trois couches. Sans exception.

Couche 1 (router.py) : enregistrement des ViewSets

# apps/transactions/router.py
from rest_framework.routers import DefaultRouter
from apps.transactions.views import TransactionViewSet, RefundViewSet

router = DefaultRouter()
router.register(r'refunds', RefundViewSet, basename='refunds')
router.register(r'', TransactionViewSet, basename='transactions')

urls_patterns = router.urls

Couche 2 (urls.py) : contrat URL de l'app

# apps/transactions/urls.py
from apps.transactions.router import urls_patterns

urlpatterns = urls_patterns

Couche 3 (backend/urls.py) : dispatcher racine, versionné

urlpatterns = [
    path("v1/auth/",          include("apps.authentication.urls")),
    path("v1/transactions/",  include("apps.transactions.urls")),
    path("v1/users/",         include("apps.users.urls")),
]

Un nouveau développeur qui cherche "d'où vient l'endpoint de liste des transactions" suit ce chemin en moins de 60 secondes. Pas de magie. Pas de chasse au trésor. 🗺️

Quand tu as besoin de /v2/, tu ajoutes un second bloc sans toucher au premier.

Bonus : scripts/ et docs/

scripts/
├── rmpycaches.py        ← Supprime tous les dossiers __pycache__
└── rmmigrationfiles.py  ← Supprime les fichiers de migration (pour les resets en dev)

docs/
└── modelings/           ← Use cases, diagrammes de classes, diagrammes de séquence

Ces petits détails signalent un codebase professionnel.

L'impact concret

Le développeur senior qui a revu mon code a avancé vite. Il pouvait naviguer sans me demander où se trouvaient les choses. C'est la métrique qui compte : pas "est-ce que le code est malin", mais "est-ce que la prochaine personne peut le lire ?"

Pendant le développement : tu ne te demandes jamais "où je mets ça ?". La structure répond à ta place. Ajouter marketing/ ne touche pas à transactions/.

Pendant la code review : les PRs restent petites, les reviewers savent exactement où regarder.

Pendant l'onboarding : un nouveau dev cartographie le codebase en 20 minutes en lisant les noms de dossiers.

Pendant les incidents : un bug dans la création de transaction ? Tu vas dans services/transaction_processor.py, pas dans un views.py de 1 000 lignes.

Pendant le refactoring : extraire notifications/ en microservice, c'est déplacer un dossier, pas grepper du code éparpillé.

La checklist récap

Pour ton prochain projet Django, ou pour refactoriser l'actuel :

• [ ] Nomme ton dossier de config backend/ (ou config/), pas d'après ton projet

• [ ] Mets toutes les apps sous apps/

• [ ] Découpe settings.py par domaine : smtp.py, storages.py, etc.

• [ ] Crée AbstractCommonBaseModel avec UUID PK, timestamps et soft delete

• [ ] Découpe models.py en fichiers models/<domaine>.py, ré-exportés via __init__.py

• [ ] Ajoute une couche services/ : les vues appellent les services, pas l'ORM directement

• [ ] Crée apps/utils/ comme bibliothèque interne du projet

• [ ] Utilise des enums pour les choix de modèles (une source de vérité)

• [ ] Suis le pattern URL en trois couches : router.py → urls.py → backend/urls.py

• [ ] Ajoute un dossier scripts/ pour les commandes dev répétitives

• [ ] Écris au moins une docs/ minimale. Ton futur toi te remerciera.

La suite

Prochain article : Gestion standardisée des erreurs dans Django REST Framework, avec support i18n et exemple d'intégration React.

Toute API retourne des erreurs. La question, c'est de savoir si elles sont cohérentes, traduisibles, et utiles pour le frontend qui les consomme. Je vous montrerai le pattern ErrorEnum + ERROR_MAP, comment drf-standardized-errors formate chaque réponse, et comment câbler tout ça pour qu'une app React affiche le bon message dans la bonne langue sans aucune chaîne de if/else.

Si tu remarques quelque chose d'incorrect, ou si tu fais les choses différemment avec de meilleurs résultats, commente en dessous. Je suis là pour apprendre autant que pour partager. 🤝