Среднее ПО

Среднее ПО — это фреймворк хуков для обработки запросов/ответов в Django. Это лёгкая, низкоуровневая система «плагинов» для глобального изменения ввода или вывода Django.

Каждый компонент среднего ПО отвечает за выполнение определённой функции. Например, Django включает компонент среднего ПО, AuthenticationMiddleware, который связывает пользователей с запросами с использованием сессий.

Этот документ объясняет, как работает среднее ПО, как его активировать и как написать собственное среднее ПО. Django поставляется с некоторым встроенным средним ПО, которое можно использовать сразу. Они документированы в справочнике встроенного среднего ПО.

Написание собственного среднего ПО

Фабрика среднего ПО — это вызываемый объект, который принимает вызываемый get_response объект и возвращает среднее ПО. Среднее ПО — это вызываемый объект, который принимает запрос и возвращает ответ, как и представление.

Среднее ПО может быть реализовано как функция, которая выглядит так:

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

Или оно может быть реализовано как класс, экземпляры которого являются вызываемыми объектами, как в этом примере:

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

Вызываемый объект get_response , предоставляемый Django, может быть фактическим представлением (если это последнее среднее ПО в списке), или это может быть следующее среднее ПО в цепочке. Текущему среднему ПО не нужно знать или заботиться о том, что это именно, а только о том, что это представляет собой следующее звено.

Вышеприведённое — это упрощённая версия. Вызываемый объект get_response для последнего среднего ПО в цепочке не будет фактическим представлением, а скорее методом-обёрткой из обработчика, который отвечает за применение среднего ПО для представлений, вызов представления с соответствующими аргументами URL и применение среднего ПО для ответов шаблонов и среднего ПО для обработки исключений.

Среднее ПО может поддерживать только синхронный Python (по умолчанию), только асинхронный Python или оба варианта. Подробности о том, как указать поддерживаемый вами тип, и о том, какой запрос вы получаете, см. в разделе Поддержка асинхронности.

Среднее ПО может находиться в любом месте на вашем пути Python.

__init__(get_response)

Фабрики среднего ПО должны принимать аргумент get_response. Вы также можете инициализировать некоторое глобальное состояние для среднего ПО. Имейте в виду несколько нюансов:

• Django инициализирует ваше среднее ПО только с аргументом get_response, поэтому вы не можете определить __init__() как требующее другие аргументы.
• В отличие от метода __call__(), который вызывается один раз на запрос, __init__() вызывается только один раз, при запуске веб-сервера.

Отмечание среднего ПО как неиспользуемого

Иногда полезно определить в момент запуска, должно ли использоваться конкретное среднее ПО. В таких случаях метод __init__() вашего среднего ПО может вызвать MiddlewareNotUsed. Затем Django удалит это среднее ПО из процесса обработки среднего ПО и выведет сообщение отладки в логгер django.request, когда DEBUG равно True.

Активация среднего ПО

Чтобы активировать компонент среднего ПО, добавьте его в список MIDDLEWARE в файле настроек Django.

В MIDDLEWARE каждый компонент среднего ПО представлен строкой: полным путём Python к классу или имени функции фабрики среднего ПО. Например, вот значение по умолчанию, созданное 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',
]

Установка Django не требует никакого среднего ПО — MIDDLEWARE может быть пустым, если вы этого хотите — но настоятельно рекомендуется хотя бы использовать CommonMiddleware.

Порядок в MIDDLEWARE имеет значение, потому что одно среднее ПО может зависеть от другого. Например, AuthenticationMiddleware сохраняет аутентифицированного пользователя в сессии; поэтому оно должно выполняться после SessionMiddleware. Подробнее об очередности классов среднего ПО Django см. в разделе Порядок среднего ПО.

Порядок и слои среднего ПО

Во время обработки запроса, перед вызовом представления, Django применяет среднее ПО в порядке, определённом в MIDDLEWARE, сверху вниз.

Вы можете представить это как лук: каждый класс среднего ПО — это «слой», который оборачивает представление, которое находится в ядре лука. Если запрос проходит через все слои лука (каждый слой вызывает get_response для передачи запроса в следующий слой), до представления в ядре, то ответ затем пройдёт через каждый слой (в обратном порядке) на пути наружу.

Если один из слоёв принимает решение об обходе и возвращает ответ, не вызывая его get_response, ни один из слоёв лука внутри этого слоя (включая представление) не увидит запрос или ответ. Ответ вернётся только через те же слои, через которые прошёл запрос.

Другие хуки среднего ПО

Помимо описанного ранее базового паттерна среднего ПО для обработки запросов/ответов, вы можете добавить три других специальных метода в классовые компоненты среднего ПО:

process_view()

process_view(request, view_func, view_args, view_kwargs)

request — это объект HttpRequest. view_func — это функция Python, которую Django собирается использовать. (Это фактический объект функции, а не имя функции как строка.) view_args — это список позиционных аргументов, которые будут переданы в представление, а view_kwargs — это словарь ключевых аргументов, которые будут переданы в представление. Ни view_args, ни view_kwargs не включают первый аргумент представления (request).

process_view() вызывается непосредственно перед тем, как Django вызывает представление.

Он должен возвращать либо None, либо объект HttpResponse. Если он возвращает None, Django продолжит обработку этого запроса, выполнив любое другое среднее ПО и, затем, соответствующее представление. Если он возвращает объект HttpResponse, Django не станет беспокоиться о вызове соответствующего представления; он применит среднее ПО для ответа к этому объекту HttpResponse и вернёт результат.

process_exception()

process_exception(request, exception)

request — это объект HttpRequest. exception — это объект Exception , поднятый функцией представления.

Django вызывает process_exception() при возникновении исключения в представлении. process_exception() должен вернуть либо None, либо объект HttpResponse. Если он возвращает объект HttpResponse, шаблоны ответа и обработчик ответа будут применены, и полученный ответ будет возвращён браузеру. В противном случае сработает обработка исключений по умолчанию.

Опять же, middleware выполняется в обратном порядке во время фазы ответа, которая включает process_exception. Если middleware обработки исключений возвращает ответ, методы process_exception классов middleware, расположенных выше этого middleware, вообще не будут вызваны.

process_template_response()

process_template_response(request, response)

request — это объект HttpRequest. response — это объект TemplateResponse (или эквивалент), возвращаемый представлением Django или middleware.

process_template_response() вызывается сразу после завершения выполнения представления, если экземпляр ответа имеет метод render(), указывающий, что это TemplateResponse или эквивалент.

Он должен вернуть объект ответа, который реализует метод render. Он может изменить предоставленный response путём изменения response.template_name и response.context_data, или он может создать и вернуть совершенно новый объект TemplateResponse или эквивалент.

Вам не нужно явно рендерить ответы — ответы будут автоматически рендериться после вызова всех middleware обработки ответа шаблонов.

Middleware выполняется в обратном порядке во время фазы ответа, которая включает process_template_response().

Обработка потоковых ответов

В отличие от HttpResponse, StreamingHttpResponse не имеет атрибута content. В результате middleware больше не может предполагать, что все ответы будут иметь атрибут content. Если им нужен доступ к содержимому, они должны проверить потоковые ответы и соответственно скорректировать своё поведение:

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

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

Обработка исключений

Django автоматически преобразует исключения, поднятые представлением или middleware, в соответствующий HTTP-ответ со статусом ошибки. Определённые исключения преобразуются в коды статуса 4xx, а неизвестное исключение преобразуется в код статуса 500.

Это преобразование происходит до и после каждого middleware (можно представить это как тонкую плёнку между каждым слоем лука), так что каждый middleware может всегда полагаться на получение какого-либо HTTP-ответа от вызова его вызываемого объекта get_response. Middleware не нужно беспокоиться об обёртке своего вызова get_response в try/except и обработке исключения, которое могло быть поднято последующим middleware или представлением. Даже если следующий middleware в цепочке поднимет исключение Http404, например, ваш middleware не увидит это исключение; вместо этого он получит объект HttpResponse с кодом статуса status_code 404.

Вы можете установить DEBUG_PROPAGATE_EXCEPTIONS в True для пропуска этого преобразования и передачи исключений вверх.

Асинхронная поддержка

Middleware может поддерживать любые комбинации синхронных и асинхронных запросов. Django адаптирует запросы к требованиям middleware, если он не может поддерживать оба, но с потерей производительности.

По умолчанию Django предполагает, что ваш middleware способен обрабатывать только синхронные запросы. Чтобы изменить эти предположения, установите следующие атрибуты в вашей фабрике middleware или классе:

• sync_capable — булево значение, указывающее, может ли middleware обрабатывать синхронные запросы. По умолчанию True.
• async_capable — булево значение, указывающее, может ли middleware обрабатывать асинхронные запросы. По умолчанию False.

Если ваш middleware имеет как sync_capable = True , так и async_capable = True, Django передаст ему запрос без преобразования. В этом случае вы можете определить, получит ли ваш middleware асинхронные запросы, проверив, является ли объект get_response, который вы получили, функцией-генератором, используя asyncio.iscoroutinefunction().

Модуль django.utils.decorators содержит декораторы sync_only_middleware(), async_only_middleware() и sync_and_async_middleware(), которые позволяют применять эти флаги к функциям-фабрикам middleware.

Возвращаемая вызываемая функция должна соответствовать синхронной или асинхронной природе метода get_response. Если у вас есть асинхронный get_response, вы должны вернуть функцию-генератор (async def).

Методы process_view, process_template_response и process_exception, если они предоставлены, также должны быть адаптированы к синхронному/асинхронному режиму. Однако Django будет индивидуально адаптировать их по мере необходимости, если вы этого не сделаете, что приведёт к дополнительной потери производительности.

Вот пример создания функции middleware, поддерживающей оба режима:

import asyncio
from django.utils.decorators import sync_and_async_middleware

@sync_and_async_middleware
def simple_middleware(get_response):
    # One-time configuration and initialization goes here.
    if asyncio.iscoroutinefunction(get_response):
        async def middleware(request):
            # Do something here!
            response = await get_response(request)
            return response

    else:
        def middleware(request):
            # Do something here!
            response = get_response(request)
            return response

    return middleware

Модернизация middleware старого стиля (pre-Django 1.10)

class django.utils.deprecation.MiddlewareMixin

Django предоставляет django.utils.deprecation.MiddlewareMixin для облегчения создания классов middleware, совместимых с MIDDLEWARE и старым стилем MIDDLEWARE_CLASSES, а также поддержки синхронных и асинхронных запросов. Все классы middleware, включённые в Django, совместимы с обоими настройками.

Mixin предоставляет метод __init__() , который требует аргумент get_response и сохраняет его в self.get_response.

Метод __call__():

1. Вызывает self.process_request(request) (если определён).
2. Вызывает self.get_response(request) для получения ответа от последующего middleware и представления.
3. Вызывает self.process_response(request, response) (если определён).
4. Возвращает ответ.

Если используется с MIDDLEWARE_CLASSES, метод __call__() никогда не будет использоваться; Django напрямую вызывает process_request() и process_response().

В большинстве случаев наследование от этого mixin будет достаточно, чтобы сделать middleware старого стиля совместимым с новой системой с достаточной обратной совместимостью. Новая семантика короткого замыкания будет безвредной или даже полезной для существующего middleware. В некоторых случаях классу middleware могут потребоваться изменения для адаптации к новой семантике.

Вот различия в поведении при использовании MIDDLEWARE и MIDDLEWARE_CLASSES:

1. Под MIDDLEWARE_CLASSES, каждый промежуточный обработчик всегда будет вызывать свой метод process_response, даже если предыдущий промежуточный обработчик прервал выполнение, вернув ответ из своего метода process_request. Согласно MIDDLEWARE, промежуточные обработчики ведут себя как слои лука: слои, через которые проходит ответ при выходе, — это те же слои, которые обрабатывали запрос при входе. Если промежуточный обработчик прерывает выполнение, только этот промежуточный обработчик и предшествующие ему в MIDDLEWARE будут видеть ответ.
2. Под MIDDLEWARE_CLASSES, process_exception применяется к исключениям, возникающим в методе промежуточного обработчика process_request. Согласно MIDDLEWARE, process_exception применяется только к исключениям, возникающим в представлении (или в методе render TemplateResponse). Исключение, возникшее в промежуточном обработчике, преобразуется в соответствующий HTTP-ответ и передаётся следующему промежуточному обработчику.
3. Под MIDDLEWARE_CLASSES, если метод process_response вызывает исключение, методы process_response всех предыдущих промежуточных обработчиков пропускаются, и всегда возвращается HTTP-ответ 500 Internal Server Error (даже если возникшее исключение, например, Http404). Согласно MIDDLEWARE, исключение, возникшее в промежуточном обработчике, немедленно преобразуется в соответствующий HTTP-ответ, а затем следующий в очереди промежуточный обработчик увидит этот ответ. Промежуточные обработчики никогда не пропускаются из-за возникновения исключения в промежуточном обработчике.