Django-中间件

这篇讲什么

  • 中间件是一套轻量、底层的钩子,可以在请求进来和响应回去的路上修改输入输出;每个中间件组件就是一个 Python 类。
  • 这篇讲新项目默认的 MIDDLEWARE 里每一项在干什么、新式与老式两种写法、为什么「顺序就是语义」,并亲手写一个注入属性 / 加响应头 / 统计耗时的中间件。实测基线 Django 5.2.19。

概述

  • 中间件是一个轻量级、底层的插件机制,可以介入 Django 的请求和响应处理过程,修改 Django 的输入或输出。
  • 每个中间件组件就是一个独立的 Python 类。典型用途:登录态注入、权限拦截、统一加响应头、耗时统计、异常兜底。
  • 请求进来时按 MIDDLEWARE 从上往下走,响应回去时从下往上走,所以顺序就是语义。

新项目默认的 MIDDLEWARE

  • 实测 startproject 生成的 7 条(顺序照抄):

    1
    2
    3
    4
    5
    6
    7
    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
    • SessionMiddleware 负责 request.session;AuthenticationMiddleware 负责 request.user,它必须排在 Session 之后,否则拿不到用户。
    • CommonMiddleware 处理 URL 规范化(APPEND_SLASH)、Expires/Last-Modified 响应头。
    • SecurityMiddleware 处理 SECURE_* 系列(强制 HTTPS、HSTS、SSL 重定向)。
    • XFrameOptionsMiddleware 加 X-Frame-Options,防点击劫持。
  • 老笔记写的 MIDDLEWARE_CLASSES 在 Django 5.2 上完全没人读,实测两条证据:

    1
    2
    3
    4
    settings.MIDDLEWARE_CLASSES = [...] 之后:
    System check identified no issues (0 silenced). # 不报错
    真正生效的 MIDDLEWARE 条数: 10 # 还是 MIDDLEWARE 那份
    base.py 里出现 MIDDLEWARE_CLASSES 的次数: 0 # 框架源码根本不提它
    • 这是典型的「静默失效」:写错键名不会有任何提示,中间件就是不生效。

两种写法:新式与老式钩子

  • 新式写法(推荐)

    myapp/middleware.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    import time


    class TimingMiddleware:
    """给每个响应加一个耗时头。"""

    def __init__(self, get_response):
    self.get_response = get_response # 服务器启动时调用一次

    def __call__(self, request):
    start = time.perf_counter()
    response = self.get_response(request) # 把请求交给下一环
    response["X-Response-Time"] = "%.6f" % (time.perf_counter() - start)
    return response
    • 实测生效:X-Response-Time: 0.004293。
    • __init__ 只在服务启动、装配中间件链时调用一次(老笔记说「服务器响应第一个请求的时候调用一次」,准确说法是装配期,不是首个请求)。
  • 老式钩子:必须继承 MiddlewareMixin

    middleware.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    from django.utils.deprecation import MiddlewareMixin


    class OldHooksMiddleware(MiddlewareMixin):
    def process_request(self, request):
    request.hit_request_hook = True # 也可以 return HttpResponse(...) 直接短路

    def process_view(self, request, view_func, view_args, view_kwargs):
    request.hit_view_hook = view_func.__name__

    def process_exception(self, request, exception):
    return HttpResponse("process_exception 接住了: %s" % exception)

    def process_template_response(self, request, response):
    response["X-Template-Hook"] = "1"
    return response
    • MiddlewareMixin 在 5.2 上仍然存在(实测 hasattr 为 True),它把这几个钩子包装成 __call__。

    • 各钩子的调用时机与返回值(实测):

      钩子 时机 返回什么会怎样
      process_request(request) request 产生后、URL 匹配前 返回 None 继续;返回 HttpResponse 直接短路,后面的中间件和视图都不执行
      process_view(request, view_func, view_args, view_kwargs) URL 匹配后、视图调用前 同上
      process_exception(request, exception) 视图抛异常时 返回响应就用它当结果;返回 None 交给下一个(实测接住后 200 b'process_exception 接住了: ...')
      process_template_response(request, response) 视图返回之后 只对 TemplateResponse 生效。实测普通 HttpResponse 时 X-Template-Hook: None
      process_response(request, response) 响应返回浏览器前 必须返回响应对象
  • 两个坑:没有 __call__、钩子写在不继承 Mixin 的类上

    1
    2
    TypeError: 'NoCallMiddleware' object is not callable
    Internal Server Error: /user_flag/
    • 也就是说:既写 __call__ 又写老式钩子是不行的,二选一;选了钩子就必须继承 MiddlewareMixin。

顺序就是语义

  • 实测把自定义中间件插在 AuthenticationMiddleware 之前,此时 request.user 还不存在:

    1
    EarlyUser 在 auth 之前: hasattr(request,'user')=False
    • 想在中间件里判断登录态,必须排在 AuthenticationMiddleware 之后。
  • 缓存中间件 UpdateCacheMiddleware / FetchFromCacheMiddleware 要求分别在首/尾,但5.2 不会帮你检查(实测放错位置 check 依然 no issues)。

  • 配置位置:

    proj/settings.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "myapp.middleware.TimingMiddleware", # 自定义的插在这里
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "myapp.middleware.OldHooksMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
    ]
    • 老笔记把中间件放在 myApp.middlewares.myMiddle.MyMiddle(包名 middlewares 复数、驼峰应用名)。按 PEP8 用 myapp.middleware(模块名一般用单数,跟 models.py、 forms.py 一致)。

在视图里用中间件注入的东西

views.py
1
2
3
def index(request):
print(request.hit_view_hook, request.description)
return render(request, "myapp/index.html")
  • 中间件给 request 挂属性是常规做法(request.user、 request.session 本身就是这么来的)。
  • 但要清楚:属性名是中间件和视图之间的私有约定,Django 不做检查,名字写错就是视图里的 AttributeError。跨应用共用时建议加前缀(myapp_profile)。

原理图

中间件

  • 老笔记这里写的是 /images/Django/中间件.png,这个路径在站点里不存在(图片实际在 static/img/Django/ 下),所以图上一直是裂的;这一版改成正确路径。

新手卡点清单

  • 都是实测过的:

    卡点 症状 正确做法
    写 MIDDLEWARE_CLASSES check 不报错,中间件不生效 写 MIDDLEWARE,改完跑 check
    只写钩子方法、不继承 MiddlewareMixin TypeError: 'XxxMiddleware' object is not callable 要么 __init__+__call__,要么继承 Mixin
    放在 AuthenticationMiddleware 前面读 request.user hasattr(request,'user') 为 False 排到 auth 之后
    指望 process_template_response 处理所有响应 普通 HttpResponse 时不被调用 只对 TemplateResponse 生效,别用它做通用改写
    __init__ 当成「首个请求时执行」 依赖它做每请求初始化的逻辑不生效 装配期只跑一次,每请求的逻辑写在 __call__
    process_exception 返回 None 异常继续往上冒,页面 500 要兜住就返回响应对象

参考

本文结束 感谢您的阅读
正在加载今日诗词....