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
      6
      >>> from 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
    13
    from 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=False

    1
    2
    >>> JsonResponse([{"name": "张三"}])
    TypeError: In order to allow non-dict objects to be serialized set the safe parameter to False.
    • 这不是 bug,是防「JSON 劫持」:只有对象字面量开头的响应才不会被老浏览器当变量赋值走。推荐做法就是老笔记那样包一层字典 {"data": [...]},既不用关 safe,前端也更好扩展。
  • 2)5.2 的 JsonResponse 没有 serialize 参数

    1
    2
    3
    >>> import 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
      2
      stu_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
    <!DOCTYPE html>
    <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
    4
    POST /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 %},或从 csrftoken Cookie 取):

    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,但那意味着放弃这层保护,别拿来当默认。

路由

  • 路由与视图名也统一成下划线:

    myapp/urls.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    from 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' %} 而不是写死。

新手卡点清单

  • 都是实测过的:

    卡点 症状 正确做法
    用 request.is_ajax() AttributeError: 'HttpRequest' object has no attribute 'is_ajax' 判 request.headers.get("x-requested-with")
    fetch 请求被当成普通访问 后端走了「返回整页」的分支 fetch 手动补 X-Requested-With 头,或后端同时看 Accept
    JsonResponse(queryset) TypeError: Object of type QuerySet is not JSON serializable 先 list(qs.values(...))
    JsonResponse(list) TypeError: ... set the safe parameter to False. 包一层字典 {"data": [...]}
    教程里抄来 serialize=True 5.2 无此参数,照样炸 用 values() 或 streams,别加这个参数
    POST 忘带 CSRF 403 Forbidden,日志 Forbidden (CSRF cookie not set.) 带 X-CSRFToken 头或表单域
    变量名用 list / 函数名驼峰 遮蔽内置、检查器报警 stu_list / show_students

参考

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