Промежуточное ПО

Промежуточное ПО — это фреймворк хуков в обработке запросов/ответов 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 продолжит обработку этого запроса, выполняя любое другое промежуточное ПО process_view() и затем соответствующее представление. Если он возвращает объект HttpResponse, Django не станет вызывать соответствующее представление; он применит промежуточное ПО ответа к этому объекту HttpResponse и вернёт результат.

process_exception()

process_exception(request, exception)

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

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

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

process_template_response()

process_template_response(request, response)

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

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

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

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

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

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

В отличие от HttpResponse, StreamingHttpResponse не имеет атрибута content. В результате средние слои больше не могут предполагать, что все ответы будут иметь атрибут 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 автоматически преобразует исключения, поднятые представлением или средними слоями, в соответствующий HTTP-ответ с кодом состояния ошибки. Некоторые исключения преобразуются в коды состояния 4xx, а неизвестное исключение преобразуется в код состояния 500.

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

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

Поддержка асинхронности

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

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

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

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

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

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

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

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

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

Обновление средних слоёв стиля до Django 1.10

class django.utils.deprecation.MiddlewareMixin

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

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

Метод __call__():

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

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

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

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

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