diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index 50f23fff31..d5958dfebd 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -240,3 +240,71 @@ X-Frame-Options middleware .. class:: XFrameOptionsMiddleware Simple :doc:`clickjacking protection via the X-Frame-Options header `. + +.. _middleware-ordering: + +Middleware ordering +=================== + +Here are some hints about the ordering of various Django middleware classes: + +#. :class:`~django.middleware.cache.UpdateCacheMiddleware` + + Before those that modify the ``Vary`` header (``SessionMiddleware``, + ``GZipMiddleware``, ``LocaleMiddleware``). + +#. :class:`~django.middleware.gzip.GZipMiddleware` + + Before any middleware that may change or use the response body. + + After ``UpdateCacheMiddleware``: Modifies ``Vary`` header. + +#. :class:`~django.middleware.http.ConditionalGetMiddleware` + + Before ``CommonMiddleware``: uses its ``Etag`` header when + :setting:`USE_ETAGS` = ``True``. + +#. :class:`~django.contrib.sessions.middleware.SessionMiddleware` + + After ``UpdateCacheMiddleware``: Modifies ``Vary`` header. + +#. :class:`~django.middleware.locale.LocaleMiddleware` + + One of the topmost, after ``SessionMiddleware`` (uses session data) and + ``CacheMiddleware`` (modifies ``Vary`` header). + +#. :class:`~django.middleware.common.CommonMiddleware` + + Before any middleware that may change the response (it calculates ``ETags``). + + After ``GZipMiddleware`` so it won't calculate an ``ETag`` header on gzipped + contents. + + Close to the top: it redirects when :setting:`APPEND_SLASH` or + :setting:`PREPEND_WWW` are set to ``True``. + +#. :class:`~django.middleware.csrf.CsrfViewMiddleware` + + Before any view middleware that assumes that CSRF attacks have been dealt + with. + +#. :class:`~django.contrib.auth.middleware.AuthenticationMiddleware` + + After ``SessionMiddleware``: uses session storage. + +#. :class:`~django.contrib.messages.middleware.MessageMiddleware` + + After ``SessionMiddleware``: can use session-based storage. + +#. :class:`~django.middleware.cache.FetchFromCacheMiddleware` + + After any middleware that modifies the ``Vary`` header: that header is used + to pick a value for the cache hash-key. + +#. :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` + + Should be near the bottom as it's a last-resort type of middleware. + +#. :class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware` + + Should be near the bottom as it's a last-resort type of middleware. diff --git a/docs/topics/http/middleware.txt b/docs/topics/http/middleware.txt index e21bdbd297..9335ecc12a 100644 --- a/docs/topics/http/middleware.txt +++ b/docs/topics/http/middleware.txt @@ -45,7 +45,9 @@ The order in :setting:`MIDDLEWARE_CLASSES` matters because a middleware can depend on other middleware. For instance, :class:`~django.contrib.auth.middleware.AuthenticationMiddleware` stores the authenticated user in the session; therefore, it must run after -:class:`~django.contrib.sessions.middleware.SessionMiddleware`. +:class:`~django.contrib.sessions.middleware.SessionMiddleware`. See +:ref:`middleware-ordering` for some common hints about ordering of Django +middleware classes. Hooks and application order ===========================