Intergiciels (« Middleware »)

Les intergiciels représentent un système de points d’entrée dans le traitement des requêtes et des réponses de Django. C’est un système de greffons léger et de bas niveau pour modifier de façon globale les entrées et sorties HTTP de Django.

Chaque composant d’intergiciel est responsable d’effectuer une tâche spécifique. Par exemple, Django contient un intergiciel, AuthenticationMiddleware, qui associe les utilisateurs aux requêtes et aux sessions.

Ce document explique comment fonctionnent les intergiciels, la manière de les activer et d’écrire vos propres intergiciels. Django est livré avec quelques intergiciels intégrés qu’il est possible d’utiliser tels quels. Ils sont documentés dans la référence des intergiciels intégrés.

Écriture de son propre intergiciel

Une fabrique d’intergiciel est un objet exécutable acceptant un exécutable get_response et renvoyant un intergiciel. Un intergiciel est un objet exécutable acceptant une requête et renvoyant une réponse, tout comme une vue.

Un intergiciel peut être écrit comme une fonction qui ressemble à ceci :

def simple_middleware(get_response):
    # One-time configuration and initialization.

    def middleware(request):
        # Code to be executed for each request before
        # the view (and later middleware) are called.

        response = get_response(request)

        # Code to be executed for each request/response after
        # the view is called.

        return response

    return middleware

Ou il peut être écrit comme une classe dont les instances peuvent être appelées, comme ceci :

class SimpleMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response
        # One-time configuration and initialization.

    def __call__(self, request):
        # Code to be executed for each request before
        # the view (and later middleware) are called.

        response = self.get_response(request)

        # Code to be executed for each request/response after
        # the view is called.

        return response

L’exécutable get_response fournit par Django pourrait être la vue elle-même (s’il s’agit du dernier intergiciel) ou alors le prochain intergiciel dans la chaîne. L’intergiciel actuel n’a pas besoin de savoir ou de se préoccuper de ce que c’est exactement, il lui suffit de savoir que ça représente ce qui vient ensuite.

Nous avons un peu simplifié l’explication ci-dessus, car l’exécutable get_response du dernier intergiciel dans la chaîne est en fait une méthode enveloppant la vue, créée par le gestionnaire se chargeant d’appliquer les intergiciels de vue; cette méthode appelle la vue avec les paramètres appropriés et applique les intergiciels template-response et exception.

Les intergiciels peuvent se trouver n’importe où dans votre chemin Python.

__init__(get_response)

Les fabriques d’intergiciel doivent accepter un paramètre get_response. Il est aussi possible d’initialiser de l’état global pour l’intergiciel. Gardez à l’esprit quelques précautions :

  • Django initialise les intergiciels avec le seul paramètre get_response, il n’est donc pas possible de définir d’autres paramètres obligatoires à __init__().
  • Contrairement à la méthode __call__() qui est appelée une fois par requête, __init__() n’est appelée qu”une seule fois, lorsque le serveur Web démarre.

Signalement d’un intergiciel à exclure

Il est parfois utile de déterminer au moment du démarrage si un intergiciel doit être utilisé. Dans ces cas, la méthode __init__() de l’intergiciel peut générer l’exception django.core.exceptions.MiddlewareNotUsed. Django se charge alors d’enlever cet intergiciel du processus des intergiciels et jouranlise un message de débogage vers le journaliseur django.request lorsque DEBUG vaut True.

Activation des intergiciels

Pour activer un intergiciel, ajoutez son chemin dans la liste MIDDLEWARE de vos réglages Django.

Dans MIDDLEWARE, chaque intergiciel est représenté par une chaîne : le chemin Python complet vers le nom de la classe ou de la fonction de fabrique d’intergiciel. Par exemple, voici la valeur par défaut créée par django-admin startproject:

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

Une installation de Django n’a pas nécessairement des intergiciels, MIDDLEWARE pouvant très bien être vide si vous le souhaitez, mais il est fortement recommandé d’utiliser au moins CommonMiddleware.

L’ordre dans MIDDLEWARE a son importance car un intergiciel peut dépendre d’un autre. Par exemple, AuthenticationMiddleware stocke l’utilisateur non authentifié dans la session ; il doit donc être exécuté après SessionMiddleware. Voir Ordre des intergiciels pour d’autres indications utiles concernant l’ordre des classes d’intergiciel de Django.

Ordre des intergiciels et empilement

Durant la phase de requête, avant d’appeler la vue, Django applique les intergiciels dans l’ordre où ils sont définis dans MIDDLEWARE, de haut en bas.

Vous pouvez l’imaginer comme un oignon : chaque classe d’intergiciel est une « couche » qui enveloppe la vue, elle-même le cœur de l’oignon. Si la requête traverse toutes les couches de l’oignon (chacune appelant get_response pour passer la requête à la prochaine couche), jusqu’à atteindre la vue au cœur, la réponse va ensuite traverser elle-même toutes les couches (dans l’ordre inverse) jusqu’à sa sortie du mécanisme.

Si l’une des couches décide de court-circuiter et de renvoyer une réponse sans jamais appeler get_response, aucune des couches de l’oignon plus à l’intérieur de cette couche (y compris la vue) ne verra la requête ou la réponse. La réponse ne traversera toujours que les mêmes couches traversées par la requête.

Autres points d’entrée d’intergiciel

En dehors du modèle basique requête/réponse d’intergiciel présenté précédemment, vous pouvez ajouter trois autres méthodes spéciales aux intergiciels basés sur des classes :

process_view()

process_view(request, view_func, view_args, view_kwargs)

request est un objet HttpRequest. view_func et la fonction python que Django s’apprête à utiliser (il s’agit bien de l’objet fonction, pas du nom textuel de la fonction). view_args est une liste de paramètres positionnels qui seront transmis à la vue, et view_kwargs est un dictionnaire de paramètres nommés qui seront transmis à la vue. Ni view_args ni view_kwargs ne comprennent le premier paramètre de la vue (request).

process_view() est appelée juste avant que Django n’appelle la vue.

Elle doit renvoyer soit None, soit un objet HttpResponse. Si elle renvoie None, Django continue le traitement de la requête, en appliquant d’éventuels autres intergiciels process_view(), puis exécute la vue appropriée. Si elle renvoie un objet HttpResponse, Django ne prend pas la peine d’appeler la vue correspondante ; il va simplement appliquer les intergiciels de réponse à cet objet HttpResponse et renvoyer le résultat.

Note

L’accès à request.POST depuis un intergiciel avant que la vue ne soit exécutée ou dans process_view() empêche toute vue exécutée après les intergiciels de pouvoir modifier les gestionnaires de téléversement de la requête, et devrait donc être évité.

La classe CsrfViewMiddleware peut être considérée comme une exception, car elle fournit les décorateurs csrf_exempt() et csrf_protect() qui permettent aux vues de contrôler explicitement le moment de la validation CSRF.

process_exception()

process_exception(request, exception)

request est un objet HttpRequest. exception est un objet Exception généré par la fonction de vue.

Django appelle process_exception() lorsqu’une vue génère une exception. process_exception() doit renvoyer None ou un objet HttpResponse. Si elle renvoie un objet HttpResponse, les intergiciels de réponse par gabarit et de réponse sont appliqués, et la réponse résultante sera renvoyée au navigateur. Sinon, la gestion par défaut des exceptions intervient.

Encore une fois, les intergiciels sont exécutés dans l’ordre inverse lors de la phase de réponse, ce qui comprend process_exception. Si un intergiciel d’exception renvoie une réponse, les méthodes process_exception des classes d’intergiciels situées au-dessus ne seront pas du tout appelées.

process_template_response()

process_template_response(request, response)

request est un objet HttpRequest. response est l’objet TemplateResponse (ou équivalent) renvoyé par une vue Django ou par un intergiciel.

process_template_response() est appelée juste après la fin de l’exécution de la vue, pour autant que l’instance réponse possède une méthode render(), ce qui laisse penser qu’il s’agit d’un objet TemplateResponse ou d’un équivalent.

Elle doit renvoyer un objet réponse qui implémente une méthode render. Elle peut modifier la réponse donnée en changeant response.template_name et response.context_data, ou elle peut créer et renvoyer une toute nouvelle classe TemplateResponse ou un équivalent.

Il n’est pas nécessaire d’effectuer explicitement le rendu des réponses, celles-ci étant automatiquement « rendues » après que tous les intergiciels de réponse ont été appelés.

Les intergiciels sont exécutés dans l’ordre inverse lors de la phase de réponse, ce qui inclut process_template_response().

Gestion des réponses en flux

Au contraire de HttpResponse, StreamingHttpResponse ne possède pas d’attribut content. En conséquence, les intergiciels ne peuvent plus compter sur le fait que toutes les réponses possèdent un attribut content. S’ils ont besoin d’accéder au contenu, ils doivent savoir s’ils ont affaire avec une réponse de type flux (streaming) et ajuster leur comportement en fonction de cela :

if response.streaming:
    response.streaming_content = wrap_streaming_content(response.streaming_content)
else:
    response.content = alter_content(response.content)

Note

Il faut toujours partir du principe que streaming_content est trop volumineux pour être stocké en mémoire. Les intergiciels de réponse peuvent l’adapter dans un nouveau générateur, mais ils ne devraient pas le consommer. L’adaptation s’implémente typiquement de cette façon :

def wrap_streaming_content(content):
    for chunk in content:
        yield alter_content(chunk)

Gestion des exceptions

Django convertit automatiquement les exceptions produites par la vue ou par l’intergiciel en une réponse HTTP appropriée avec un code de statut d’erreur. Certaine exceptions sont converties en codes de statut 4xx, alors qu’une exception inconnue est convertie en un code de statut 500.

Cette conversion a lieu avant et après chaque intergiciel (vous pouvez vous représenter cela comme la fine peau entre chaque couche de l’oignon), afin que chaque intergiciel puisse toujours compter sur l’obtention d’un certain type de réponse HTTP en retour de son appel à get_response. Les intergiciels n’ont pas besoin se se soucier d’envelopper leur appel à get_response dans un bloc try/except pour gérer une exception qui aurait pu être générée par un intergiciel suivant ou par la vue. Même si l’intergiciel suivant dans la chaîne génère une exception Http404, par exemple, votre intergiciel ne verra pas cette exception ; il obtiendra à la place un objet HttpResponse avec un code status_code 404.

Mise à jour d’intergiciels écrits avant Django 1.10

class django.utils.deprecation.MiddlewareMixin

Django provides django.utils.deprecation.MiddlewareMixin to ease creating middleware classes that are compatible with both MIDDLEWARE and the old MIDDLEWARE_CLASSES. All middleware classes included with Django are compatible with both settings.

Cette classe « mixin » fournit une méthode __init__() acceptant un paramètre facultatif get_response et le stockant dans self.get_response.

La méthode __call__():

  1. Appelle self.process_request(request) (si elle est définie).
  2. Appelle self.get_response(request) pour obtenir la réponse du dernier intergiciel et de la vue.
  3. Appelle self.process_response(request, response) (si elle est définie).
  4. Renvoie la réponse.

If used with MIDDLEWARE_CLASSES, the __call__() method will never be used; Django calls process_request() and process_response() directly.

Dans la plupart des cas, l’héritage de cette classe « mixin » suffit à rendre compatible un intergiciel ancien style avec le nouveau système avec suffisamment de rétro-compatibilité. La nouvelle sémantique de court-circuitage ne fera pas de mal ou sera même avantageuse pour l’intergiciel existant. Dans quelques cas, une classe d’intergiciel pourrait avoir besoin de certains changements pour s’ajuster à la nouvelle sémantique.

These are the behavioral differences between using MIDDLEWARE and MIDDLEWARE_CLASSES:

  1. Under MIDDLEWARE_CLASSES, every middleware will always have its process_response method called, even if an earlier middleware short-circuited by returning a response from its process_request method. Under MIDDLEWARE, middleware behaves more like an onion: the layers that a response goes through on the way out are the same layers that saw the request on the way in. If a middleware short-circuits, only that middleware and the ones before it in MIDDLEWARE will see the response.
  2. Under MIDDLEWARE_CLASSES, process_exception is applied to exceptions raised from a middleware process_request method. Under MIDDLEWARE, process_exception applies only to exceptions raised from the view (or from the render method of a TemplateResponse). Exceptions raised from a middleware are converted to the appropriate HTTP response and then passed to the next middleware.
  3. Under MIDDLEWARE_CLASSES, if a process_response method raises an exception, the process_response methods of all earlier middleware are skipped and a 500 Internal Server Error HTTP response is always returned (even if the exception raised was e.g. an Http404). Under MIDDLEWARE, an exception raised from a middleware will immediately be converted to the appropriate HTTP response, and then the next middleware in line will see that response. Middleware are never skipped due to a middleware raising an exception.
Back to Top