Django-Ajax
这篇讲什么
- 页面和数据绑死在一起时,同一份列表要写两个视图,前端想局部刷新只能整页重载。
- 这篇让一个视图同时返回 HTML 和 JSON,把
JsonResponse的三个坑实测一遍,前端以fetch为主、jQuery 作对照,最后说清 Ajax 请求为什么要带 CSRF 头。基线 Django 5.2.19。
问题
- 用视图通过上下文向模板传数据,要先加载完静态页面、再执行模型代码、生成完整 HTML 返回浏览器,页面与数据被绑死在一起,扩展性差。
- 典型症状:同一个「学生列表」,页面要一份、接口要一份,只能再写一个视图;前端想局部刷新只能整页重载。
解决
- 用 Ajax 拿数据,再用 DOM 操作把数据呈现在页面上:后端只回 JSON,页面不重载。
- 老笔记这套写法在 Django 5.2 上仍然成立,但判断「是不是 Ajax 请求」的那行代码已经换掉了,而且
JsonResponse有几个必须知道的坑,下面逐条实测。
后端:一个视图同时给页面和给数据
-
is_ajax()已经被删了-
Django 1.x 到 4.x 时代大家写
if request.is_ajax():。实测在 5.2.19 上:1
2
3
4
5
6from django.test import RequestFactory
r = RequestFactory().get("/")
hasattr(r, "is_ajax")
False
r.is_ajax()
AttributeError: 'HttpRequest' object has no attribute 'is_ajax' -
这个方法在 Django 3.1 被弃用、5.0 正式移除。官方给的替代就是自己看请求头,这也是老笔记后来改用的写法:
1
if request.headers.get("x-requested-with") == "XMLHttpRequest":
request.headers是META里HTTP_*的只读视图,所以request.headers.get("x-requested-with")实际读的是request.META["HTTP_X_REQUESTED_WITH"],大小写不敏感。- 这个头是 jQuery / axios 等库自动加的,原生
fetch不会加。所以下面用 fetch 时要么手动补这个头,要么改用「Accept 头 + 参数」判断,别默认它一定在。
-
-
视图(PEP8 命名,变量不遮蔽内置)
myapp/views.py 1
2
3
4
5
6
7
8
9
10
11
12
13from django.http import JsonResponse
from django.shortcuts import render
from myapp.models import Student
def show_students(request):
"""同一个视图:浏览器直接访问给页面,Ajax 请求给 JSON。"""
if request.headers.get("x-requested-with") == "XMLHttpRequest":
stu_list = [{"name": stu.name, "age": stu.age}
for stu in Student.objects.all()]
return JsonResponse({"data": stu_list})
return render(request, "myapp/show_students.html")-
老笔记这里有两个不规范的地方,一并改掉:变量名叫
list(遮蔽了内置的list类型)、函数名叫showStudents(驼峰)。 -
实测两种请求的差别(同一 URL,只多一个请求头):
1
2
3不带 x-requested-with -> 200 / text/html; charset=utf-8(渲染模板)
带 x-requested-with -> 200 / application/json,体形如
{"data": [{"name": "\u5f20\u4e09", "age": 18}, ...]}- 中文被转义成
\uXXXX是json.dumps的默认行为(ensure_ascii=True),浏览器JSON.parse之后是正常的;想让响应里直接看到中文,传json_dumps_params={"ensure_ascii": False}。
- 中文被转义成
-
JsonResponse 的三个坑
-
1)直接给列表要
safe=False1
2JsonResponse([{"name": "张三"}])
TypeError: In order to allow non-dict objects to be serialized set the safe parameter to False.- 这不是 bug,是防「JSON 劫持」:只有对象字面量开头的响应才不会被老浏览器当变量赋值走。推荐做法就是老笔记那样包一层字典
{"data": [...]},既不用关safe,前端也更好扩展。
- 这不是 bug,是防「JSON 劫持」:只有对象字面量开头的响应才不会被老浏览器当变量赋值走。推荐做法就是老笔记那样包一层字典
-
2)5.2 的
JsonResponse没有serialize参数1
2
3import inspect
inspect.signature(JsonResponse.__init__)
(self, data, encoder=DjangoJSONEncoder, safe=True, json_dumps_params=None, **kwargs)-
网上有些教程写
JsonResponse(queryset, safe=False, serialize=True),在 5.2 上serialize会被当成**kwargs里的HttpResponse参数吞掉,结果照样炸:1
TypeError: Object of type QuerySet is not JSON serializable
-
正确做法是在视图里先把查询集转成可序列化的结构:
1
2stu_list = list(Student.objects.values("name", "age"))
return JsonResponse({"data": stu_list})values()返回的是「字典组成的 QuerySet」,list()之后就能直接序列化;带外键时用values("name", "grade_id")或select_related()后再取字段。
-
-
3)日期、Decimal 现在默认可序列化
-
老笔记会说「
date/datetime/Decimal必须显式传encoder=DjangoJSONEncoder」。这条已经过时:Django 5.0 起JsonResponse的默认encoder就是DjangoJSONEncoder(上面签名里也能看到)。实测:1
2
3{"x": "2026-11-04"}
{"x": "2026-11-04T01:02:03"}
{"x": "3.14"} -
仍然不能直接序列化的是模型对象本身、
QuerySet、UUID之外的自定义类型 —— 那些要么转成字典,要么自己写 encoder。
-
前端写法:fetch 为主,jQuery 作对照
-
fetch(现代写法,不引任何库)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<html lang="zh">
<head>
<meta charset="UTF-8">
<title>学生信息</title>
</head>
<body>
<button id="btn">查看学生</button>
<ul id="stu_list"></ul>
<script>
document.getElementById("btn").addEventListener("click", async () => {
const resp = await fetch("/show_students/", {
headers: {
"X-Requested-With": "XMLHttpRequest",
"Accept": "application/json",
},
});
const payload = await resp.json();
const ul = document.getElementById("stu_list");
ul.innerHTML = "";
for (const stu of payload.data) {
const li = document.createElement("li");
li.textContent = stu.name + " / " + stu.age;
ul.appendChild(li);
}
});
</script>
</body>
</html>- 三个要点:
fetch默认就带同源 Cookie;要后端认它是 Ajax 得自己补X-Requested-With;fetch只有在网络层失败才 reject,HTTP 4xx/5xx 不会进catch,要自己看resp.ok。
- 三个要点:
-
老笔记的 jQuery 写法
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19<script type="text/javascript" src="/static/js/jquery-3.1.1.min.js"></script>
<script type="text/javascript">
$(function () {
$("#btn").bind("click", function () {
$.ajax({
type: "get",
url: "/show_students/",
data: {"a": 1, "b": 1},
dataType: "json",
success: function (data, status) {
var stus = data["data"];
for (var i = 0; i < stus.length; i++) {
$("#stulist").append($("<li>" + stus[i].name + "</li>"));
}
}
});
});
});
</script>$.get()是$.ajax({type:"get"})的简写,两者行为一致,$.ajax()可控项更多(超时、beforeSend、error)。- jQuery 会自动加
X-Requested-With: XMLHttpRequest,所以后端那行判断只对 jQuery/axios 这类库有效。 $.get()/$.ajax()/.bind()都还在 jQuery 3.x 里可用(.bind()官方已标弃用,推荐.on())。- 版本要留意:老笔记引的是
jquery-3.1.1.min.js,实测该 CDN 地址仍然活着(https://code.jquery.com/jquery-3.1.1.min.js返回 200,86709 字节),但 3.1.1 有已知安全问题,新项目至少上 3.7.x(https://cdn.jsdelivr.net/npm/jquery@3.7.1/dist/jquery.min.js实测 200)。
Ajax 与 CSRF
-
POST 一个带
CsrfViewMiddleware的接口时,不带 token 会被拦。实测:1
2
3
4POST /post_echo/ 不带 token -> 403 Forbidden
服务端日志:Forbidden (CSRF cookie not set.): /post_echo/
POST /post_echo/ 带 X-CSRFToken -> 200 {"ok": true, "name": "abc"}
表单域 csrfmiddlewaretoken 同样 200 -
fetch 里带 token 的常见做法(页面里放
{% csrf_token %},或从csrftokenCookie 取):1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20<form method="post" action="/post_echo/">
{% csrf_token %}
<input type="text" name="name">
</form>
<script>
function getCookie(name) {
const m = document.cookie.match("(^|;)\\s*" + name + "\\s*=\\s*([^;]+)");
return m ? m.pop() : "";
}
fetch("/post_echo/", {
method: "POST",
headers: {
"X-CSRFToken": getCookie("csrftoken"),
"Content-Type": "application/json",
},
body: JSON.stringify({name: "abc"}),
});
</script>- 只读接口(GET)不需要 token;Django 默认对
GET/HEAD/OPTIONS/TRACE跳过 CSRF 检查。 - 确实要豁免某个接口时用
@csrf_exempt,但那意味着放弃这层保护,别拿来当默认。
- 只读接口(GET)不需要 token;Django 默认对
路由
-
路由与视图名也统一成下划线:
myapp/urls.py 1
2
3
4
5
6
7
8
9
10from django.urls import path
from myapp import views
app_name = "myapp"
urlpatterns = [
path("show_students/", views.show_students, name="show_students"),
path("post_echo/", views.post_echo, name="post_echo"),
]- URL 路径也按 PEP8 风格用下划线(老笔记写的是
/showStudents/),并且给每条都起name,前端拼 URL 时可以用{% url 'myapp:show_students' %}而不是写死。
- URL 路径也按 PEP8 风格用下划线(老笔记写的是
新手卡点清单
-
都是实测过的:
卡点 症状 正确做法 用 request.is_ajax()AttributeError: 'HttpRequest' object has no attribute 'is_ajax'判 request.headers.get("x-requested-with")fetch 请求被当成普通访问 后端走了「返回整页」的分支 fetch 手动补 X-Requested-With头,或后端同时看AcceptJsonResponse(queryset)TypeError: Object of type QuerySet is not JSON serializable先 list(qs.values(...))JsonResponse(list)TypeError: ... set the safe parameter to False.包一层字典 {"data": [...]}教程里抄来 serialize=True5.2 无此参数,照样炸 用 values()或streams,别加这个参数POST 忘带 CSRF 403 Forbidden,日志Forbidden (CSRF cookie not set.)带 X-CSRFToken头或表单域变量名用 list/ 函数名驼峰遮蔽内置、检查器报警 stu_list/show_students
参考
- Django
JsonResponse参考:safe、encoder、json_dumps_params的官方说明。 - Django 3.1 release notes(
is_ajax()弃用) 与 5.0 release notes(移除):替代写法就是看X-Requested-With。 - MDN:Using
fetch:默认带 Cookie、4xx 不 reject 这些行为差异。 - jQuery AJAX:
$.ajax/$.get选项与dataType说明。