中间件

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

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

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

编写自己的中间件

中间件工厂是一个可调用的程序,它接受 get_response 可调用并返回中间件。中间件是可调用的,它接受请求并返回响应,就像视图一样。

中间件可以被写成这样的函数:

  1. def simple_middleware(get_response):
  2. # One-time configuration and initialization.
  3.  
  4. def middleware(request):
  5. # Code to be executed for each request before
  6. # the view (and later middleware) are called.
  7.  
  8. response = get_response(request)
  9.  
  10. # Code to be executed for each request/response after
  11. # the view is called.
  12.  
  13. return response
  14.  
  15. return middleware

或者它可以写成一个类,它的实例是可调用的,如下:

  1. class SimpleMiddleware:
  2. def __init__(self, get_response):
  3. self.get_response = get_response
  4. # One-time configuration and initialization.
  5.  
  6. def __call__(self, request):
  7. # Code to be executed for each request before
  8. # the view (and later middleware) are called.
  9.  
  10. response = self.get_response(request)
  11.  
  12. # Code to be executed for each request/response after
  13. # the view is called.
  14.  
  15. return response

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

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

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

init(get_response)

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

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

标记未使用的中间件

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

激活中间件

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

MIDDLEWARE 中,每个中间件组件由字符串表示:指向中间件工厂的类或函数名的完整 Python 路径。例如,这里创建的默认值是 django-admin startproject

  1. MIDDLEWARE = [
  2. 'django.middleware.security.SecurityMiddleware',
  3. 'django.contrib.sessions.middleware.SessionMiddleware',
  4. 'django.middleware.common.CommonMiddleware',
  5. 'django.middleware.csrf.CsrfViewMiddleware',
  6. 'django.contrib.auth.middleware.AuthenticationMiddleware',
  7. 'django.contrib.messages.middleware.MessageMiddleware',
  8. 'django.middleware.clickjacking.XFrameOptionsMiddleware',
  9. ]

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 withoutever calling its get_response, none of the layers of the onion inside thatlayer (including the view) will see the request or the response. The responsewill only return through the same layers that the request passed in through.

Other middleware hooks

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

process_view()

  • processview(_request, view_func, view_args, view_kwargs)
  • request is an HttpRequest object. view_func isthe Python function that Django is about to use. (It's the actual functionobject, not the name of the function as a string.) view_args is a list ofpositional arguments that will be passed to the view, and view_kwargs is adictionary of keyword arguments that will be passed to the view. Neitherview_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 HttpResponseobject. If it returns None, Django will continue processing this request,executing any other process_view() middleware and, then, the appropriateview. If it returns an HttpResponse object, Django won'tbother calling the appropriate view; it'll apply response middleware to thatHttpResponse and return the result.

注解

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

The CsrfViewMiddleware class can beconsidered an exception, as it provides thecsrf_exempt() andcsrf_protect() decorators which allowviews to explicitly control at what point the CSRF validation should occur.

process_exception()

  • processexception(_request, exception)
  • request is an HttpRequest object. exception is anException object raised by the view function.

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

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

process_template_response()

  • processtemplate_response(_request, response)
  • request is an HttpRequest object. response isthe TemplateResponse object (or equivalent)returned by a Django view or by a middleware.

process_template_response() is called just after the view has finishedexecuting, if the response instance has a render() method, indicating thatit is a TemplateResponse or equivalent.

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

You don't need to explicitly render responses — responses will beautomatically rendered once all template response middleware has beencalled.

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

Dealing with streaming responses

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

  1. if response.streaming:
  2. response.streaming_content = wrap_streaming_content(response.streaming_content)
  3. else:
  4. response.content = alter_content(response.content)

注解

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 consumeit. Wrapping is typically implemented as follows:

  1. def wrap_streaming_content(content):
  2. for chunk in content:
  3. yield alter_content(chunk)

异常处理

Django automatically converts exceptions raised by the view or by middlewareinto an appropriate HTTP response with an error status code. Certainexceptions are converted to 4xx status codes, while an unknownexception is converted to a 500 status code.

This conversion takes place before and after each middleware (you can think ofit as the thin film in between each layer of the onion), so that everymiddleware can always rely on getting some kind of HTTP response back fromcalling its get_response callable. Middleware don't need to worry aboutwrapping their call to get_response in a try/except and handling anexception that might have been raised by a later middleware or the view. Evenif the very next middleware in the chain raises anHttp404 exception, for example, your middleware won't seethat exception; instead it will get an HttpResponseobject 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 creatingmiddleware classes that are compatible with both MIDDLEWARE and theold MIDDLEWARE_CLASSES. All middleware classes included with Djangoare compatible with both settings.

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

The call() method:

  • Calls self.process_request(request) (if defined).
  • Calls self.get_response(request) to get the response from latermiddleware and the view.
  • Calls self.process_response(request, response) (if defined).
  • Returns the response.
    If used with MIDDLEWARECLASSES, the _call() method willnever be used; Django calls process_request() and process_response()directly.

In most cases, inheriting from this mixin will be sufficient to make anold-style middleware compatible with the new system with sufficientbackwards-compatibility. The new short-circuiting semantics will be harmless oreven beneficial to the existing middleware. In a few cases, a middleware classmay need some changes to adjust to the new semantics.

These are the behavioral differences between using MIDDLEWARE andMIDDLEWARE_CLASSES:

  • Under MIDDLEWARE_CLASSES, every middleware will always have itsprocess_response method called, even if an earlier middlewareshort-circuited by returning a response from its process_requestmethod. Under MIDDLEWARE, middleware behaves more like an onion:the layers that a response goes through on the way out are the same layersthat saw the request on the way in. If a middleware short-circuits, onlythat middleware and the ones before it in MIDDLEWARE will see theresponse.
  • Under MIDDLEWARE_CLASSES, process_exception is applied toexceptions raised from a middleware process_request method. UnderMIDDLEWARE, process_exception applies only to exceptionsraised from the view (or from the render method of aTemplateResponse). Exceptions raised froma middleware are converted to the appropriate HTTP response and then passedto the next middleware.
  • Under MIDDLEWARE_CLASSES, if a process_response method raisesan exception, the process_response methods of all earlier middleware areskipped and a 500 Internal Server Error HTTP response is alwaysreturned (even if the exception raised was e.g. anHttp404). Under MIDDLEWARE, an exceptionraised from a middleware will immediately be converted to the appropriateHTTP response, and then the next middleware in line will see thatresponse. Middleware are never skipped due to a middleware raising anexception.