Django2.0手册:中间件

中间件是 Django 请求/响应处理的钩子框架。它是一个轻量级的、低级的“插件”系统,用于全局改变 Django 的输入或输出。

每个中间件组件负责做一些特定的功能。例如,Django 包含一个中间件组件 AuthenticationMiddleware,它使用会话将用户与请求关联起来。

他的文档解释了中间件是如何工作的,如何激活中间件,以及如何编写自己的中间件。Django 具有一些内置的中间件,你可以直接使用。它们被记录在 built-in middleware reference 中。

编写自己的中间件¶

中间件工厂是一个可调用的程序,它接受 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

Django 提供的 get_response 响应可能是实际视图(如果这是最后列出的中间件),或者它可能是链中的下一个中间件。不需要知道或关心当前的中间件到底是什么,它只是代表了下一步的内容。

以上是一个轻微的简化——链中最后一个中间件调用的 get_response 可不是实际视图,而是处理程序的包装方法,它负责应用 view middleware,调用具有适当URL参数的视图,并应用 template-responseexception 中间件。

中间件可以放在 Python 路径上的任何地方。

__init__(get_response)¶

中间件工厂必须接受 get_response 参数。还可以初始化中间件的一些全局状态。记住两个注意事项:

  • Django仅用 get_response 参数初始化您的中间件,因此不能定义 __init__() ,因为需要其他参数。
  • 与每次请求调用 __call__() 方法不同,当 Web 服务器启动时,__init__() 只被称为*一次*。

标记未使用的中间件¶

在启动时确定是否应该使用一个中间件有时是有用的。在这些情况下,您的中间件的 __init__() 方法可能会引发 MiddlewareNotUsed。Django 将从中间件进程中删除该中间件,并将调试消息记录到 django.request 日志:设置 DEBUGTrue

激活中间件¶

若要激活中间件组件,请将其添加到 Django 设置中的 MIDDLEWARE 列表中。

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 后面运行 。中间件。Session中间件。请参阅 Middleware ordering ,用于一些关于 Django 中间件类排序的常见提示。

中间件顺序与分层¶

在请求阶段,在调用视图之前,Django 按照定义的顺序应用中间件 MIDDLEWARE,自顶向下。

你可以把它想象成一个洋葱:每个中间件类都是一个“层”,它覆盖了洋葱的核心。如果请求通过洋葱的所有层(每一个调用 get_response )以将请求传递到下一层,一直到内核的视图,那么响应将在返回的过程中通过每个层(以相反的顺序)。

If one of the layers decides to short-circuit and return a response without
ever calling its get_response, none of the layers of the onion inside that
layer (including the view) will see the request or the response. The response
will only return through the same layers that the request passed in through.

Other middleware hooks¶

Besides the basic request/response middleware pattern described earlier, you
can add three other special methods to class-based middleware:

process_view()¶

process_view(request, view_func, view_args, view_kwargs)

request is an HttpRequest object. view_func is
the Python function that Django is about to use. (It’s the actual function
object, not the name of the function as a string.) view_args is a list of
positional arguments that will be passed to the view, and view_kwargs is a
dictionary of keyword arguments that will be passed to the view. Neither
view_args nor view_kwargs include the first view argument
(request).

process_view() is called just before Django calls the view.

It should return either None or an HttpResponse
object. If it returns None, Django will continue processing this request,
executing any other process_view() middleware and, then, the appropriate
view. If it returns an HttpResponse object, Django won’t
bother calling the appropriate view; it’ll apply response middleware to that
HttpResponse and return the result.

Note

Accessing request.POST inside
middleware before the view runs or in process_view() will prevent any
view running after the middleware from being able to modify the
upload handlers for the request
,
and should normally be avoided.

The CsrfViewMiddleware class can be
considered an exception, as it provides the
csrf_exempt() and
csrf_protect() decorators which allow
views to explicitly control at what point the CSRF validation should occur.

process_exception()¶

process_exception(request, exception)

request is an HttpRequest object. exception is an
Exception object raised by the view function.

Django calls process_exception() when a view raises an exception.
process_exception() should return either None or an
HttpResponse object. If it returns an
HttpResponse object, the template response and response
middleware will be applied and the resulting response returned to the
browser. Otherwise, default exception handling kicks in.

Again, middleware are run in reverse order during the response phase, which
includes process_exception. If an exception middleware returns a response,
the process_exception methods of the middleware classes above that
middleware won’t be called at all.

process_template_response()¶

process_template_response(request, response)

request is an HttpRequest object. response is
the TemplateResponse object (or equivalent)
returned by a Django view or by a middleware.

process_template_response() is called just after the view has finished
executing, if the response instance has a render() method, indicating that
it is a TemplateResponse or equivalent.

It must return a response object that implements a render method. It could
alter the given response by changing response.template_name and
response.context_data, or it could create and return a brand-new
TemplateResponse or equivalent.

You don’t need to explicitly render responses — responses will be
automatically rendered once all template response middleware has been
called.

Middleware are run in reverse order during the response phase, which
includes process_template_response().

Dealing with streaming responses¶

Unlike HttpResponse,
StreamingHttpResponse does not have a content
attribute. As a result, middleware can no longer assume that all responses
will have a content attribute. If they need access to the content, they
must test for streaming responses and adjust their behavior accordingly:

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

Note

streaming_content should be assumed to be too large to hold in memory.
Response middleware may wrap it in a new generator, but must not consume
it. Wrapping is typically implemented as follows:

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

Exception handling¶

Django automatically converts exceptions raised by the view or by middleware
into an appropriate HTTP response with an error status code. Certain
exceptions
are converted to 4xx status codes, while an unknown
exception is converted to a 500 status code.

This conversion takes place before and after each middleware (you can think of
it as the thin film in between each layer of the onion), so that every
middleware can always rely on getting some kind of HTTP response back from
calling its get_response callable. Middleware don’t need to worry about
wrapping their call to get_response in a try/except and handling an
exception that might have been raised by a later middleware or the view. Even
if the very next middleware in the chain raises an
Http404 exception, for example, your middleware won’t see
that exception; instead it will get an HttpResponse
object with a status_code of 404.

Upgrading pre-Django 1.10-style middleware¶

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.

The mixin provides an __init__() method that accepts an optional
get_response argument and stores it in self.get_response.

The __call__() method:

  1. Calls self.process_request(request) (if defined).
  2. Calls self.get_response(request) to get the response from later
    middleware and the view.
  3. Calls self.process_response(request, response) (if defined).
  4. Returns the response.

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

In most cases, inheriting from this mixin will be sufficient to make an
old-style middleware compatible with the new system with sufficient
backwards-compatibility. The new short-circuiting semantics will be harmless or
even beneficial to the existing middleware. In a few cases, a middleware class
may need some changes to adjust to the new semantics.

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.