Django-中间件
这篇讲什么
- 中间件是一套轻量、底层的钩子,可以在请求进来和响应回去的路上修改输入输出;每个中间件组件就是一个 Python 类。
- 这篇讲新项目默认的
MIDDLEWARE里每一项在干什么、新式与老式两种写法、为什么「顺序就是语义」,并亲手写一个注入属性 / 加响应头 / 统计耗时的中间件。实测基线 Django 5.2.19。
概述
- 中间件是一个轻量级、底层的插件机制,可以介入 Django 的请求和响应处理过程,修改 Django 的输入或输出。
- 每个中间件组件就是一个独立的 Python 类。典型用途:登录态注入、权限拦截、统一加响应头、耗时统计、异常兜底。
- 请求进来时按
MIDDLEWARE从上往下走,响应回去时从下往上走,所以顺序就是语义。
新项目默认的 MIDDLEWARE
-
实测
startproject生成的 7 条(顺序照抄):1
2
3
4
5
6
7django.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.XFrameOptionsMiddlewareSessionMiddleware负责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
4settings.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
14import 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__只在服务启动、装配中间件链时调用一次(老笔记说「服务器响应第一个请求的时候调用一次」,准确说法是装配期,不是首个请求)。
- 实测生效:
-
老式钩子:必须继承
MiddlewareMixinmiddleware.py 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16from 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: Noneprocess_response(request, response)响应返回浏览器前 必须返回响应对象
-
-
两个坑:没有
__call__、钩子写在不继承 Mixin 的类上1
2TypeError: '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
11MIDDLEWARE = [
"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一致)。
- 老笔记把中间件放在
在视图里用中间件注入的东西
1 | def index(request): |
- 中间件给
request挂属性是常规做法(request.user、request.session本身就是这么来的)。 - 但要清楚:属性名是中间件和视图之间的私有约定,Django 不做检查,名字写错就是视图里的
AttributeError。跨应用共用时建议加前缀(myapp_profile)。
原理图

- 老笔记这里写的是
/images/Django/中间件.png,这个路径在站点里不存在(图片实际在static/img/Django/下),所以图上一直是裂的;这一版改成正确路径。
新手卡点清单
-
都是实测过的:
卡点 症状 正确做法 写 MIDDLEWARE_CLASSEScheck不报错,中间件不生效写 MIDDLEWARE,改完跑check只写钩子方法、不继承 MiddlewareMixinTypeError: 'XxxMiddleware' object is not callable要么 __init__+__call__,要么继承 Mixin放在 AuthenticationMiddleware前面读request.userhasattr(request,'user')为False排到 auth 之后 指望 process_template_response处理所有响应普通 HttpResponse时不被调用只对 TemplateResponse生效,别用它做通用改写__init__当成「首个请求时执行」依赖它做每请求初始化的逻辑不生效 装配期只跑一次,每请求的逻辑写在 __call__process_exception返回None异常继续往上冒,页面 500 要兜住就返回响应对象
参考
- Django 中间件总览:可用钩子清单与顺序语义。
- 编写自定义中间件:新式
__init__/__call__的官方写法。 MiddlewareMixin:老式钩子的兼容层。- 内置中间件参考:
SecurityMiddleware、CommonMiddleware等各自的作用与依赖顺序。