写Django后端有一段时间了从最早用函数视图拼HTML到后来用类视图、DRF写接口模板语法和请求响应这三块一直没绕开过。“模板语法、请求与响应”听起来像是Django入门三件套但真正把这三样吃透前端后端协作起来会顺畅很多。尤其现在全栈项目里前端可能是Vue、可能是Uniapp、也可能是小程序Django往往充当的不只是渲染页面的人还得是提供数据接口的人。这篇文章就把这三块掰开揉碎讲清楚它们底层的逻辑再配合一个完整的图书管理小例子把从请求进来、视图处理、模板渲染、响应返回的完整链路走一遍。1. 请求到达Django之后发生了什么先花点时间把请求的生命周期讲明白。很多新手学Django上来就写视图函数知道def index(request)里面能拿到request.method知道返回render还是JsonResponse但不太清楚请求从浏览器发出来之后Django内部是怎么一步步处理的。这块理解了后面排错会省很多事。1.1 一次HTTP请求的完整链路用户在浏览器里输入网址按下回车浏览器会构造一个HTTP请求带上请求行方法、路径、协议版本、请求头Host、User-Agent、Cookie、Content-Type等、请求体GET请求一般是空的POST请求一般有表单数据或JSON然后通过网络发到服务器。服务器这边跑的是WSGI服务器常见的有Gunicorn、uWSGI开发时用Django自带的runserverWSGI服务器把HTTP请求解析成一个Python层面的environ字典再交给Django的WSGIHandler去处理。Django内部拿到这个请求之后会先经过中间件链。中间件的作用有点像安检闸门SecurityMiddleware做安全头处理SessionMiddleware处理会话CsrfViewMiddleware检查CSRF令牌这些都是在这个环节做的。过了中间件请求就到了URLconf路由层Django拿请求路径去和urlpatterns里的规则做匹配匹配成功就调用对应的视图函数匹配失败就返回404。视图函数是这个链路的核心处理单元它接收到一个HttpRequest对象经过逻辑处理之后必须返回一个HttpResponse对象。这个响应对象再原路返回经过中间件最终由WSGI服务器写回给浏览器。1.2 request对象里到底藏了哪些信息视图函数签名def some_view(request)里的request就是django.http.HttpRequest的实例。它承载了这次请求的所有信息。我用得最多的几个属性和方法request.method字符串取值一般是GET、POST、PUT、DELETE等。这是判断请求方式的入口也是后面写增删改查接口第一个要判断的东西。request.GETQueryDict对象保存URL查询参数。比如/books/?page2size10request.GET.get(page)就是2。注意它是QueryDict不是普通字典调用.get()是安全的键不存在返回None不会抛KeyError。request.POSTQueryDict对象保存表单POST数据。前端用axios默认的application/x-www-form-urlencoded编码发送数据后端能通过request.POST.get(name)直接拿到。但要明确一点如果前端用application/json发请求体request.POST里是拿不到数据的得从request.body里取JSON再解析。request.body原始请求体字节串。前端发JSON、发文件、发任意自定义格式的请求体都能在body里拿到原始内容。配合json.loads(request.body)就能拿到Python字典。request.headers请求头字典拿User-Agent、Authorization、X-CSRFToken之类的都从这取。request.META一个更大的字典包含所有的HTTP头、服务器环境变量等基本信息。request.META[REMOTE_ADDR]能拿到客户端IP。request.FILES文件上传时用保存上传的文件对象。前端用multipart/form-data格式上传文件时文件数据在FILES里其他字段在POST里。request.session经过SessionMiddleware处理后才有用于服务端会话数据管理。request.user经过AuthenticationMiddleware处理后才有是当前登录用户对象。没登录一般是匿名用户AnonymousUser。1.3 GET与POST前后端联调最常见的两种请求全栈项目里GET和POST是用的最多的两种请求方式。GET一般用于读取数据POST用于提交数据。语义上的区别很重要但很多初学者容易忽略。GET请求的参数是拼在URL后面的也就是查询字符串。Django后端用request.GET.get()获取。前端用axios.get(/api/books/, { params: { page: 1 } })发送最终请求URL是/api/books/?page1。要注意GET请求不应该用来做有副作用的操作比如删除一条数据用GET也能做但语义不对浏览器预取、爬虫都可能导致误操作。我一般约定查询用GET新增用POST修改用PUT/PATCH删除用DELETE。前后端都要遵守这个约定。POST请求的参数放在请求体里。这里有个前端开发者容易踩的坑POST数据编码格式到底是什么。前端如果写的是axios.post(/api/books/, { name: Django入门, price: 59.9 })axios默认会把这个JavaScript对象序列化成JSON字符串请求头里的Content-Type是application/json。这种情况下Django的request.POST是空的数据全在request.body里。你得这样处理import json def create_book(request): if request.method POST: data json.loads(request.body) name data.get(name) price data.get(price)如果前端是用表单提交的比如const formData new URLSearchParams(); formData.append(name, Django入门); formData.append(price, 59.9); axios.post(/api/books/, formData)这就是application/x-www-form-urlencoded编码Django后端直接用request.POST.get(name)就能拿到。如果前端用的是FormData对象比如有文件上传的场景编码方式是multipart/form-dataDjango后端用request.POST.get()取普通字段request.FILES.get()取文件。这三种情况我在项目里都碰到过写接口前先确认前端发的什么编码格式能少走很多弯路。2. 响应返回不只是return一个字符串那么简单视图函数的最终使命是返回一个HttpResponse对象。新手常见的误区是视图里直接return helloDjango会报错因为必须返回的是一个响应对象。Django封装了一些快捷函数用起来很方便但理解它们底层做了什么很重要。2.1 HttpResponse、render、redirect、JsonResponse怎么选HttpResponse是最基础的响应类直接传入字符串内容就行。可以设置状态码、设置响应头。from django.http import HttpResponse def plain_text(request): resp HttpResponse(h1Hello Django/h1) resp[X-Powered-By] DjangoBlog return resprender是渲染模板最常用的快捷方式。它的内部逻辑是把请求对象和模板上下文传给模板引擎模板渲染成字符串包装成HttpResponse返回。from django.shortcuts import render def book_list(request): books Book.objects.all() return render(request, book/list.html, {books: books})redirect用于重定向返回302状态码浏览器收到之后会重新请求Location头的地址。from django.shortcuts import redirect def after_create(request): return redirect(/books/)JsonResponse是Django 1.7引入的一个便捷类专门用来返回JSON数据。它继承自HttpResponse把数据序列化成JSON字符串并且把Content-Type设置为application/json。from django.http import JsonResponse def book_detail(request, book_id): book Book.objects.get(pkbook_id) return JsonResponse({ id: book.id, name: book.name, price: book.price, })这里有个很重要但很多新手不知道的细节JsonResponse默认只支持字典对象。如果你想返回列表需要设置safeFalsedef book_list_api(request): books Book.objects.values(id, name, price) return JsonResponse(list(books), safeFalse)不设置的话直接传列表会抛TypeError: In order to allow non-dict objects to be serialized set the safe parameter to False。中文编码是另一个容易踩的坑。JsonResponse默认把非ASCII字符转成\uXXXX格式如果想让前端直接看到中文字符要设置json_dumps_params{ensure_ascii: False}return JsonResponse({name: Django入门}, json_dumps_params{ensure_ascii: False})2.2 状态码的语义后端要主动给前端准确反馈写接口时状态码的选择是一个约定问题。HTTP状态码在语义上已经有约定前后端联调时应该遵守不要自己发明。状态码含义使用场景200请求成功GET查询正常返回201资源创建成功POST新增数据成功204无内容操作成功但不需要返回内容比如DELETE301永久重定向页面永久迁移302临时重定向登录后跳转400请求参数错误缺少必填字段、参数格式不对401未认证没登录或Token失效403无权限已登录但没有访问权限404资源不存在URL错误或记录不存在500服务器内部错误代码异常我习惯在API里用一个统一的结构体包装数据比如成功时返回{code: 0, message: success, data: {...}}失败时返回{code: 40001, message: 参数错误, data: null}。HTTP状态码和业务码并存前端可以基于HTTP状态码做统一的错误拦截再基于业务码做具体的业务提示。JsonResponse默认状态码是200创建资源时记得显式设置201from django.http import JsonResponse def create_book(request): # ... 省略创建逻辑 return JsonResponse({code: 0, message: 创建成功}, status201)2.3 设置响应头跨域、缓存控制、下载文件HttpResponse对象支持像操作字典一样设置响应头。三个最常见的场景跨域CORS。Django默认不允许跨域请求安装django-cors-headers之后配置CORS_ALLOWED_ORIGINS或者在后端手动设置响应头def api_view(request): resp JsonResponse({data: ok}) resp[Access-Control-Allow-Origin] https://example.com return resp不过生产环境建议还是用django-cors-headers库统一管理不要在每个视图里手写。下载文件。设置Content-Disposition响应头可以让浏览器弹出下载框def download_report(request): content 报表内容... resp HttpResponse(content) resp[Content-Type] text/plain; charsetutf-8 resp[Content-Disposition] attachment; filenamereport.txt return resp缓存控制。对不敏感的静态查询接口可以设置短时间的缓存头减少重复查询resp[Cache-Control] max-age3003. Django模板语法后端渲染页面的核心语言在前后端分离的架构下Django模板的任务被轻量化了很多。但如果是写后台管理系统、服务端渲染页面或者做混合渲染首页服务端渲染提升SEO、内部页面走接口模板语法依然是必须掌握的技能。3.1 变量渲染双重花括号与点号取值规则模板里输出变量用双重花括号{{ variable }}。视图函数通过render的第三个参数传递上下文def index(request): context { site_name: Ming的博客, articles_count: 18, } return render(request, index.html, context)模板里写{{ site_name }}就会输出Ming的博客。这里的核心机制是点号.取值。模板里写{{ user.username }}Django会按照固定顺序解析先尝试字典键user[username]再尝试对象属性user.username再尝试列表索引user[0]等。这个顺序很重要也是很多新手犯迷糊的地方。举个例子context { user: {name: Ming, age: 25}, }模板写{{ user.name }}Django先把它当成字典取键user[name]拿到Ming。如果user是一个普通的Python对象有name属性同样可以{{ user.name }}。如果是一个列表[a, b]可以写{{ item.0 }}取第一个元素。但注意变量名解析规则里如果字典键和对象属性同时存在字典键优先。所以如果user对象有一个name属性同时user本身又是一个字典不可能因为两者是同一对象不会冲突。这里更需要小心的是模板变量解析失败时不会抛异常而是渲染成空字符串。比如{{ user.email }}如果user没有email这个键或属性页面静默地输出空这在调试时很迷惑。3.2 过滤器模板里的轻量数据处理函数模板过滤器是一种类函数的表达式格式是{{ variable|filter_name }}可以理解为管道把变量传给过滤器处理返回值输出到页面上。过滤器可以链式调用{{ text|truncatechars:20|linebreaks }}。常用过滤器清单过滤器作用示例default变量为空时给默认值{{ namelength求长度可用于字符串、列表、字典{{ booksdate格式化日期{{ create_timetruncatechars截断字符串超过部分用省略号{{ contentjoin用指定分隔符合并列表{{ tagslower/upper转换大小写{{ nameslice切片{{ contentsafe标记为安全字符串不做HTML转义{{ contentfloatformat格式化浮点数{{ price这里重点说一下safe过滤器这是模板安全机制里最关键的点。Django模板默认会对所有变量输出做HTML转义把转成lt;、转成gt;、转成amp;、引号转成#39;等。为什么要这么设计因为如果某个变量来自用户输入用户提交了一段scriptalert(xss)/script直接输出到页面上就会执行脚本。HTML转义之后这段内容会以纯文本形式显示在页面上不会执行。拿我自己的博客项目打比方文章内容如果允许用户输入HTML在模板里渲染就必须用{{ content|safe }}。但用safe的前提是你应该确保这个内容经过了白名单过滤比如只允许部分标签、属性而不是盲目信任用户输入。这也是模板引擎比纯字符串拼接更稳妥的原因。3.3 模板标签逻辑控制与代码复用模板标签的语法是{% tag %}。最基础的是if和for{% if books %} ul {% for book in books %} li{{ book.name }} - ¥{{ book.price }}/li {% empty %} li暂时没有书籍/li {% endfor %} /ul {% else %} p还没有上架任何书籍/p {% endif %}for标签里Django内置了一些循环变量比如forloop.counter是从1开始计数的序号forloop.counter0从0开始forloop.first判断是否是第一个元素forloop.last判断是否是最后一个。写表格、输出序号时这些变量很好用。模板继承是模板语言里最有价值的功能。一个典型的网站头部导航、底部信息、侧边栏在每个页面基本一样如果每个页面都复制一份后期维护就是灾难。模板继承的做法首先是基础模板base.html!DOCTYPE html html langzh-CN head meta charsetUTF-8 title{% block title %}默认标题{% endblock %}/title link relstylesheet href{% static css/style.css %} /head body header网站导航/header main {% block content %} {% endblock %} /main footer底部版权信息/footer /body /html子模板book/list.html这样继承{% extends base.html %} {% block title %}书籍列表 - 我的图书馆{% endblock %} {% block content %} h1书籍列表/h1 ... {% endblock %}extends标签必须是子模板的第一个标签block标签定义可以被覆盖的区块。父模板里block中的默认内容在子模板没有覆盖相应block的时候生效。这样可以做到有一个统一骨架每个页面细节自定义的效果。include标签用于引入子模板片段{% include common/pagination.html %}include和extends的区别在于extends是继承关系一个模板只允许一个父模板include是组合关系一个页面可以多次引入不同的局部模板片段。还有一个常用的url标签它根据URL配置里的name参数反向生成URL路径避免在模板里硬编码链接# urls.py path(books/int:pk/, views.book_detail, namebook_detail),模板里使用a href{% url book_detail book.pk %}查看详情/a如果URL配置发生调整只要name不变模板里不需要改动。这个标签在做项目重构时能省下大量时间。static标签则用于生成静态文件路径{% load static %} link relstylesheet href{% static css/style.css %}注意第一行的{% load static %}不能省略这是加载static模板标签库的声明不过Django 3.0以后内置模板里static会默认可用。{% load static %}这句写了也没关系。3.4 模板语法的执行流程与常见误区深入理解模板的执行机制能帮助排查一些诡异的问题。模板渲染的步骤大致是Django加载模板文件解析成模板对象渲染时传入的上下文Context变量会被收集到一个变量栈中模板里的变量通过名称去这个栈里查找。这个查找机制带来一个容易困惑的点在for循环里如果你循环变量名和外层某个变量名相同会覆盖外层的。比如context {book: 外层变量}模板里{% for book in books %} {{ book.name }} {% endfor %} {{ book }}循环结束后{{ book }}输出了什么答案是最后一个循环元素而不是外层变量。因为for循环结束后循环变量并不会因为作用域结束而消失它还在当前上下文里覆盖了同名的外层变量。这是我实际项目里踩过的坑在模板里循环变量名用了item结果模板底部想引用传进来的item对象输出却变成了循环里的最后一个元素。处理办法是在模板里尽量使用不冲突的变量名循环变量用book_item、article_item这类有区分的命名或者循环里用as关键字把循环结果暂存。模板里不能写Python表达式只有变量、过滤器、标签这三类基础能力。部分新手在模板里写{{ request.user.is_authenticated and request.user.is_staff }}想做个逻辑判断模板会报错。应该改为{% if request.user.is_authenticated and request.user.is_staff %}if标签支持and、or、not、in等运算符支持括号。模板语法的设计目标是保持展示层简单把复杂的逻辑放在视图层处理。4. 实战搭建一个图书管理小功能纸上谈兵讲再多理论不如把代码过一遍。下面用一个图书管理的小项目做演示把前面讲的模板语法、请求处理、响应返回全部串起来。这个项目的业务足够简单图书列表展示 新增图书表单提交但覆盖了Django开发中最核心的几块内容。4.1 项目初始化与配置假设Django已经安装好了Python环境准备好了。我用Django 3.2版本新版4.x也可以用基础语法基本没变。django-admin startproject library_project cd library_project python manage.py startapp books创建好应用之后第一步是去settings.py注册应用顺便配置templates目录和数据库这里用默认的SQLite就够了# settings.py INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, books, # 注册自己创建的应用 ] TEMPLATES [ { BACKEND: django.template.backends.django.DjangoTemplates, DIRS: [BASE_DIR / templates], APP_DIRS: True, OPTIONS: { context_processors: [ django.template.context_processors.debug, django.template.context_processors.request, django.contrib.auth.context_processors.auth, django.contrib.messages.context_processors.messages, ], }, }, ] STATIC_URL static/ STATICFILES_DIRS [BASE_DIR / static]APP_DIRS: True的意思是Django会在每个应用的templates子目录下查找模板文件。我习惯同时建一个项目级的templates目录放公共页面比如base.html所以DIRS也要配置。4.2 模型定义与数据核心在books/models.py里定义一个简单的Book模型from django.db import models class Book(models.Model): name models.CharField(max_length200, verbose_name书名) author models.CharField(max_length100, verbose_name作者) price models.DecimalField(max_digits6, decimal_places2, verbose_name价格) published_date models.DateField(verbose_name出版日期) class Meta: ordering [-id] def __str__(self): return self.name执行数据库迁移python manage.py makemigrations python manage.py migrate为了演示方便进python manage.py shell插入几条测试数据python manage.py shellfrom books.models import Book Book.objects.create(nameDjango入门指南, author张三, price59.90, published_date2024-01-15) Book.objects.create(namePython Web开发实战, author李四, price79.00, published_date2024-03-20)4.3 URL路由与视图函数设计在library_project/urls.py里引入书的应用路由from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(books/, include(books.urls)), ]在books/urls.py里定义路由from django.urls import path from . import views urlpatterns [ path(, views.book_list, namebook_list), path(create/, views.book_create, namebook_create), ]视图函数是重头戏book_list处理GET请求展示列表数据book_create需要同时处理GET展示表单页和POST接收表单提交from django.shortcuts import render, redirect from django.http import JsonResponse from django.views.decorators.http import require_http_methods from .models import Book from .forms import BookForm def book_list(request): books Book.objects.all() return render(request, books/list.html, {books: books}) require_http_methods([GET, POST]) def book_create(request): if request.method POST: form BookForm(request.POST) if form.is_valid(): form.save() return redirect(book_list) else: form BookForm() return render(request, books/create.html, {form: form})这里用了一个叫BookForm的东西它其实是Django的ModelForm。用表单可以自动化处理字段校验、错误提示、CSRF令牌验证比自己手动request.POST.get()然后逐个校验要省事得多也安全得多。在books/forms.py里定义from django import forms from .models import Book class BookForm(forms.ModelForm): class Meta: model Book fields [name, author, price, published_date] widgets { published_date: forms.DateInput(attrs{type: date}), }4.4 模板文件编写项目级templates/base.html作为公共骨架{% load static %} !DOCTYPE html html langzh-CN head meta charsetUTF-8 title{% block title %}默认标题{% endblock %}/title link relstylesheet href{% static css/style.css %} /head body nav a href{% url book_list %}图书列表/a a href{% url book_create %}新增图书/a /nav main {% block content %}{% endblock %} /main /body /htmlbooks/templates/books/list.html{% extends base.html %} {% block title %}图书列表{% endblock %} {% block content %} h1图书列表/h1 {% if books %} table border1 cellpadding8 cellspacing0 tr thID/th th书名/th th作者/th th价格/th th出版日期/th /tr {% for book in books %} tr td{{ book.id }}/td td{{ book.name }}/td td{{ book.author }}/td td¥{{ book.price }}/td td{{ book.published_date|date:Y-m-d }}/td /tr {% endfor %} /table {% else %} p暂时没有图书数据。/p {% endif %} {% endblock %}books/templates/books/create.html{% extends base.html %} {% block title %}新增图书{% endblock %} {% block content %} h1新增图书/h1 form methodpost {% csrf_token %} {{ form.as_p }} button typesubmit保存/button /form {% endblock %}这里有个关键细节form表单里那一行{% csrf_token %}必须保留。没有这行提交POST表单时Django会返回403。这个标签会在表单里渲染一个隐藏的csrfmiddlewaretoken输入框值是一串随机令牌。Django的CsrfViewMiddleware在接收POST请求时会验证这个令牌防止跨站请求伪造攻击。4.5 代码运行效果与请求链路回溯在项目根目录执行python manage.py runserver浏览器访问http://127.0.0.1:8000/books/会看到图书列表页面。访问http://127.0.0.1:8000/books/create/填完表单点保存POST请求发出后经过CSRF验证、表单校验然后重定向回列表页能看到新增的图书记录出现在列表里。把这条链路的每个环节再对照一遍浏览器访问/books/路径发出了GET /books/请求Django的URL路由通过path(, ...)匹配到book_list视图视图函数查询Book.objects.all()拿到所有图书的QuerySetrender函数把books变量放入模板上下文渲染books/list.html模板引擎在{% for book in books %}循环里逐条输出数据通过{{ book.name }}等变量访问每条记录字段渲染完成的HTML字符串包装进HttpResponse返回给浏览器这个链路理解透了Django开发的大半个流程就已经在掌握之中了。5. 常见问题与排查技巧实录最后这部分把我做Django项目时踩过的坑、被问得最多的问题整理成速查表。这些问题分散在不同项目里反复出现过每一条背后都有一个真实的故事。5.1 请求处理类问题问题现象可能原因解决方案request.POST.get(name)返回None前端发送的是JSON数据不是表单编码使用json.loads(request.body)解析POST请求返回403提示CSRF验证失败表单或请求里缺少csrftoken模板表单加{% csrf_token %}AJAX请求在请求头加X-CSRFTokenrequest.GET.get(page)拿到的是字符串不是数字GET参数本来就是字符串转换类型int(request.GET.get(page, 1))注意捕获ValueError上传文件后request.FILES为空没有设置表单enctypemultipart/form-data表单加上enctypemultipart/form-data属性URL带中文参数时视图拿到乱码编码问题前端用encodeURIComponent编码后端用quote/unquote处理或用Django自带处理CSRF这一条值得多说一句。前后端分离项目里前端用Vue或小程序发POST请求没法像模板表单那样直接渲染csrfmiddlewaretoken隐藏字段。常见做法是后端提供一个接口读取Cookie里的csrftoken前端在每次请求时把它放进请求头发送过来。Django的CsrfViewMiddleware验证逻辑是优先检查请求头X-CSRFToken里的值是否与Cookie里的csrftoken匹配匹配则通过验证否则再检查POST表单里的csrfmiddlewaretoken字段。所以前端用axios可以这样写axios.defaults.headers.common[X-CSRFToken] getCookie(csrftoken);5.2 响应结果类问题问题现象可能原因解决方案JsonResponse返回中文变成\uXXXX默认ensure_asciiTrue设置json_dumps_params{ensure_ascii: False}直接返回列表给JsonResponse报TypeError默认只接受字典传入safeFalse接口超时且无日志视图内某个数据库查询死锁或外部请求阻塞检查数据库慢查询外部HTTP请求加超时时间下载文件中文名乱码Content-Disposition里中文没编码用urllib.parse.quote处理文件名前端拿不到响应头里的自定义字段跨域时没有暴露该响应头服务端设置Access-Control-Expose-Headers: X-Custom-Header5.3 模板渲染类问题问题现象可能原因解决方案{{ user.name }}输出为空变量名拼写错误或user里没有name键/属性在视图里打印context确认键名模板调试时用{% debug %}标签页面出现script标签源码不执行Django对变量输出做了HTML转义这是安全机制确认内容是可信的用{{ contentfor循环里用book.name取不到值循环变量名和上下文变量名冲突检查循环变量是否被覆盖改变量名{% block content %}里的内容没显示子模板里block名写错或没有{% extends %}确认父模板和子模板的block名称完全一致{% extends base.html %}报错找不到模板TEMPLATES配置里DIRS没配或模板放错位置把base.html放在templates目录下确认路径这里特别提一下调试模板问题的技巧。Django模板变量解析失败不会报错而是输出空字符串这个特性对新手很不友好。我的排查经验是在视图里把传入模板的context打印出来看一眼。或者用Django的{% debug %}模板标签在页面底部输出所有上下文变量一眼就能看到有没有你要的那个变量、变量名是不是拼错了。5.4 静态文件加载不出来问得最多的问题之一就是样式加载不了。开发环境下出现这个问题的原因基本是这么几个settings.py里STATIC_URL没配置模板里没写{% load static %}static目录下文件路径拼错没有执行python manage.py collectstatic这个在生产环境才需要开发模式下runserver会自动从应用目录下的static子目录和STATICFILES_DIRS指定的目录寻找静态文件。我的目录结构一般是library_project/ library_project/ settings.py static/ css/ style.css books/ static/ books/ js/ main.js templates/ base.html模板里这样引用{% load static %} link relstylesheet href{% static css/style.css %}记住{% static %}标签生成的是URL路径比如/static/css/style.css它背后映射到静态文件目录但不等于直接拼接STATICFILES_DIRS里的路径。调试时可以先用浏览器直接访问http://127.0.0.1:8000/static/css/style.css如果能打开就说明静态文件本身没问题问题大概率出在模板引用上。5.5 排查工具与习惯做完一个Django接口或者页面我习惯在浏览器开发者工具里看一遍完整请求网络面板里看请求URL、请求方法、状态码、请求头、响应体。这一步能快速判断问题是出在前端还是后端。比如接口返回了500响应体里往往会有Django的HTML错误页面展开能看到堆栈信息定位问题很快。后端这边开发时DEBUGTrue时Django会提供详细的错误页面包含异常堆栈、SQL语句、上下文变量基本等于一个免费的调试器。但生产环境必须把DEBUGFalse不然会泄露代码路径、配置信息。我自己还有一个习惯在项目里安装django-debug-toolbar开发模式下页面侧边会显示一个调试工具条能看到所有SQL查询、请求头、模板渲染时间等信息排查数据库N1查询和慢接口特别有用。写在最后Django的模板语法、请求与响应这三块表面上看是三个独立的知识点实际是同一个链路的不同环节。请求到达Django视图函数处理业务逻辑要么用模板把数据渲染成HTML页面返回要么用JsonResponse把数据打包成JSON返回给前端。理解了这个链路的全貌无论你是做服务端渲染的传统Django项目还是做前后端分离的全栈项目都能得心应手。我在实际项目中最大的体会是写视图函数之前先想清楚前端到底需要什么。如果是页面跳转用render渲染模板如果是数据交互用JsonResponse返回结构化的JSON如果需要先处理再跳转用redirect。想清楚这个再动手代码会简洁很多。还有一个用了很久的小技巧视图函数的逻辑尽量不要写得太长POST和GET分支分开处理校验逻辑尽量用Django Form或Serializer封装起来这样代码的可维护性会好很多。这套思路从我最早用Django写个人博客到现在做企业级的全栈项目一直都适用。
写Django后端有一段时间了从最早用函数视图拼HTML到后来用类视图、DRF写接口模板语法和请求响应这三块一直没绕开过。“模板语法、请求与响应”听起来像是Django入门三件套但真正把这三样吃透前端后端协作起来会顺畅很多。尤其现在全栈项目里前端可能是Vue、可能是Uniapp、也可能是小程序Django往往充当的不只是渲染页面的人还得是提供数据接口的人。这篇文章就把这三块掰开揉碎讲清楚它们底层的逻辑再配合一个完整的图书管理小例子把从请求进来、视图处理、模板渲染、响应返回的完整链路走一遍。1. 请求到达Django之后发生了什么先花点时间把请求的生命周期讲明白。很多新手学Django上来就写视图函数知道def index(request)里面能拿到request.method知道返回render还是JsonResponse但不太清楚请求从浏览器发出来之后Django内部是怎么一步步处理的。这块理解了后面排错会省很多事。1.1 一次HTTP请求的完整链路用户在浏览器里输入网址按下回车浏览器会构造一个HTTP请求带上请求行方法、路径、协议版本、请求头Host、User-Agent、Cookie、Content-Type等、请求体GET请求一般是空的POST请求一般有表单数据或JSON然后通过网络发到服务器。服务器这边跑的是WSGI服务器常见的有Gunicorn、uWSGI开发时用Django自带的runserverWSGI服务器把HTTP请求解析成一个Python层面的environ字典再交给Django的WSGIHandler去处理。Django内部拿到这个请求之后会先经过中间件链。中间件的作用有点像安检闸门SecurityMiddleware做安全头处理SessionMiddleware处理会话CsrfViewMiddleware检查CSRF令牌这些都是在这个环节做的。过了中间件请求就到了URLconf路由层Django拿请求路径去和urlpatterns里的规则做匹配匹配成功就调用对应的视图函数匹配失败就返回404。视图函数是这个链路的核心处理单元它接收到一个HttpRequest对象经过逻辑处理之后必须返回一个HttpResponse对象。这个响应对象再原路返回经过中间件最终由WSGI服务器写回给浏览器。1.2 request对象里到底藏了哪些信息视图函数签名def some_view(request)里的request就是django.http.HttpRequest的实例。它承载了这次请求的所有信息。我用得最多的几个属性和方法request.method字符串取值一般是GET、POST、PUT、DELETE等。这是判断请求方式的入口也是后面写增删改查接口第一个要判断的东西。request.GETQueryDict对象保存URL查询参数。比如/books/?page2size10request.GET.get(page)就是2。注意它是QueryDict不是普通字典调用.get()是安全的键不存在返回None不会抛KeyError。request.POSTQueryDict对象保存表单POST数据。前端用axios默认的application/x-www-form-urlencoded编码发送数据后端能通过request.POST.get(name)直接拿到。但要明确一点如果前端用application/json发请求体request.POST里是拿不到数据的得从request.body里取JSON再解析。request.body原始请求体字节串。前端发JSON、发文件、发任意自定义格式的请求体都能在body里拿到原始内容。配合json.loads(request.body)就能拿到Python字典。request.headers请求头字典拿User-Agent、Authorization、X-CSRFToken之类的都从这取。request.META一个更大的字典包含所有的HTTP头、服务器环境变量等基本信息。request.META[REMOTE_ADDR]能拿到客户端IP。request.FILES文件上传时用保存上传的文件对象。前端用multipart/form-data格式上传文件时文件数据在FILES里其他字段在POST里。request.session经过SessionMiddleware处理后才有用于服务端会话数据管理。request.user经过AuthenticationMiddleware处理后才有是当前登录用户对象。没登录一般是匿名用户AnonymousUser。1.3 GET与POST前后端联调最常见的两种请求全栈项目里GET和POST是用的最多的两种请求方式。GET一般用于读取数据POST用于提交数据。语义上的区别很重要但很多初学者容易忽略。GET请求的参数是拼在URL后面的也就是查询字符串。Django后端用request.GET.get()获取。前端用axios.get(/api/books/, { params: { page: 1 } })发送最终请求URL是/api/books/?page1。要注意GET请求不应该用来做有副作用的操作比如删除一条数据用GET也能做但语义不对浏览器预取、爬虫都可能导致误操作。我一般约定查询用GET新增用POST修改用PUT/PATCH删除用DELETE。前后端都要遵守这个约定。POST请求的参数放在请求体里。这里有个前端开发者容易踩的坑POST数据编码格式到底是什么。前端如果写的是axios.post(/api/books/, { name: Django入门, price: 59.9 })axios默认会把这个JavaScript对象序列化成JSON字符串请求头里的Content-Type是application/json。这种情况下Django的request.POST是空的数据全在request.body里。你得这样处理import json def create_book(request): if request.method POST: data json.loads(request.body) name data.get(name) price data.get(price)如果前端是用表单提交的比如const formData new URLSearchParams(); formData.append(name, Django入门); formData.append(price, 59.9); axios.post(/api/books/, formData)这就是application/x-www-form-urlencoded编码Django后端直接用request.POST.get(name)就能拿到。如果前端用的是FormData对象比如有文件上传的场景编码方式是multipart/form-dataDjango后端用request.POST.get()取普通字段request.FILES.get()取文件。这三种情况我在项目里都碰到过写接口前先确认前端发的什么编码格式能少走很多弯路。2. 响应返回不只是return一个字符串那么简单视图函数的最终使命是返回一个HttpResponse对象。新手常见的误区是视图里直接return helloDjango会报错因为必须返回的是一个响应对象。Django封装了一些快捷函数用起来很方便但理解它们底层做了什么很重要。2.1 HttpResponse、render、redirect、JsonResponse怎么选HttpResponse是最基础的响应类直接传入字符串内容就行。可以设置状态码、设置响应头。from django.http import HttpResponse def plain_text(request): resp HttpResponse(h1Hello Django/h1) resp[X-Powered-By] DjangoBlog return resprender是渲染模板最常用的快捷方式。它的内部逻辑是把请求对象和模板上下文传给模板引擎模板渲染成字符串包装成HttpResponse返回。from django.shortcuts import render def book_list(request): books Book.objects.all() return render(request, book/list.html, {books: books})redirect用于重定向返回302状态码浏览器收到之后会重新请求Location头的地址。from django.shortcuts import redirect def after_create(request): return redirect(/books/)JsonResponse是Django 1.7引入的一个便捷类专门用来返回JSON数据。它继承自HttpResponse把数据序列化成JSON字符串并且把Content-Type设置为application/json。from django.http import JsonResponse def book_detail(request, book_id): book Book.objects.get(pkbook_id) return JsonResponse({ id: book.id, name: book.name, price: book.price, })这里有个很重要但很多新手不知道的细节JsonResponse默认只支持字典对象。如果你想返回列表需要设置safeFalsedef book_list_api(request): books Book.objects.values(id, name, price) return JsonResponse(list(books), safeFalse)不设置的话直接传列表会抛TypeError: In order to allow non-dict objects to be serialized set the safe parameter to False。中文编码是另一个容易踩的坑。JsonResponse默认把非ASCII字符转成\uXXXX格式如果想让前端直接看到中文字符要设置json_dumps_params{ensure_ascii: False}return JsonResponse({name: Django入门}, json_dumps_params{ensure_ascii: False})2.2 状态码的语义后端要主动给前端准确反馈写接口时状态码的选择是一个约定问题。HTTP状态码在语义上已经有约定前后端联调时应该遵守不要自己发明。状态码含义使用场景200请求成功GET查询正常返回201资源创建成功POST新增数据成功204无内容操作成功但不需要返回内容比如DELETE301永久重定向页面永久迁移302临时重定向登录后跳转400请求参数错误缺少必填字段、参数格式不对401未认证没登录或Token失效403无权限已登录但没有访问权限404资源不存在URL错误或记录不存在500服务器内部错误代码异常我习惯在API里用一个统一的结构体包装数据比如成功时返回{code: 0, message: success, data: {...}}失败时返回{code: 40001, message: 参数错误, data: null}。HTTP状态码和业务码并存前端可以基于HTTP状态码做统一的错误拦截再基于业务码做具体的业务提示。JsonResponse默认状态码是200创建资源时记得显式设置201from django.http import JsonResponse def create_book(request): # ... 省略创建逻辑 return JsonResponse({code: 0, message: 创建成功}, status201)2.3 设置响应头跨域、缓存控制、下载文件HttpResponse对象支持像操作字典一样设置响应头。三个最常见的场景跨域CORS。Django默认不允许跨域请求安装django-cors-headers之后配置CORS_ALLOWED_ORIGINS或者在后端手动设置响应头def api_view(request): resp JsonResponse({data: ok}) resp[Access-Control-Allow-Origin] https://example.com return resp不过生产环境建议还是用django-cors-headers库统一管理不要在每个视图里手写。下载文件。设置Content-Disposition响应头可以让浏览器弹出下载框def download_report(request): content 报表内容... resp HttpResponse(content) resp[Content-Type] text/plain; charsetutf-8 resp[Content-Disposition] attachment; filenamereport.txt return resp缓存控制。对不敏感的静态查询接口可以设置短时间的缓存头减少重复查询resp[Cache-Control] max-age3003. Django模板语法后端渲染页面的核心语言在前后端分离的架构下Django模板的任务被轻量化了很多。但如果是写后台管理系统、服务端渲染页面或者做混合渲染首页服务端渲染提升SEO、内部页面走接口模板语法依然是必须掌握的技能。3.1 变量渲染双重花括号与点号取值规则模板里输出变量用双重花括号{{ variable }}。视图函数通过render的第三个参数传递上下文def index(request): context { site_name: Ming的博客, articles_count: 18, } return render(request, index.html, context)模板里写{{ site_name }}就会输出Ming的博客。这里的核心机制是点号.取值。模板里写{{ user.username }}Django会按照固定顺序解析先尝试字典键user[username]再尝试对象属性user.username再尝试列表索引user[0]等。这个顺序很重要也是很多新手犯迷糊的地方。举个例子context { user: {name: Ming, age: 25}, }模板写{{ user.name }}Django先把它当成字典取键user[name]拿到Ming。如果user是一个普通的Python对象有name属性同样可以{{ user.name }}。如果是一个列表[a, b]可以写{{ item.0 }}取第一个元素。但注意变量名解析规则里如果字典键和对象属性同时存在字典键优先。所以如果user对象有一个name属性同时user本身又是一个字典不可能因为两者是同一对象不会冲突。这里更需要小心的是模板变量解析失败时不会抛异常而是渲染成空字符串。比如{{ user.email }}如果user没有email这个键或属性页面静默地输出空这在调试时很迷惑。3.2 过滤器模板里的轻量数据处理函数模板过滤器是一种类函数的表达式格式是{{ variable|filter_name }}可以理解为管道把变量传给过滤器处理返回值输出到页面上。过滤器可以链式调用{{ text|truncatechars:20|linebreaks }}。常用过滤器清单过滤器作用示例default变量为空时给默认值{{ namelength求长度可用于字符串、列表、字典{{ booksdate格式化日期{{ create_timetruncatechars截断字符串超过部分用省略号{{ contentjoin用指定分隔符合并列表{{ tagslower/upper转换大小写{{ nameslice切片{{ contentsafe标记为安全字符串不做HTML转义{{ contentfloatformat格式化浮点数{{ price这里重点说一下safe过滤器这是模板安全机制里最关键的点。Django模板默认会对所有变量输出做HTML转义把转成lt;、转成gt;、转成amp;、引号转成#39;等。为什么要这么设计因为如果某个变量来自用户输入用户提交了一段scriptalert(xss)/script直接输出到页面上就会执行脚本。HTML转义之后这段内容会以纯文本形式显示在页面上不会执行。拿我自己的博客项目打比方文章内容如果允许用户输入HTML在模板里渲染就必须用{{ content|safe }}。但用safe的前提是你应该确保这个内容经过了白名单过滤比如只允许部分标签、属性而不是盲目信任用户输入。这也是模板引擎比纯字符串拼接更稳妥的原因。3.3 模板标签逻辑控制与代码复用模板标签的语法是{% tag %}。最基础的是if和for{% if books %} ul {% for book in books %} li{{ book.name }} - ¥{{ book.price }}/li {% empty %} li暂时没有书籍/li {% endfor %} /ul {% else %} p还没有上架任何书籍/p {% endif %}for标签里Django内置了一些循环变量比如forloop.counter是从1开始计数的序号forloop.counter0从0开始forloop.first判断是否是第一个元素forloop.last判断是否是最后一个。写表格、输出序号时这些变量很好用。模板继承是模板语言里最有价值的功能。一个典型的网站头部导航、底部信息、侧边栏在每个页面基本一样如果每个页面都复制一份后期维护就是灾难。模板继承的做法首先是基础模板base.html!DOCTYPE html html langzh-CN head meta charsetUTF-8 title{% block title %}默认标题{% endblock %}/title link relstylesheet href{% static css/style.css %} /head body header网站导航/header main {% block content %} {% endblock %} /main footer底部版权信息/footer /body /html子模板book/list.html这样继承{% extends base.html %} {% block title %}书籍列表 - 我的图书馆{% endblock %} {% block content %} h1书籍列表/h1 ... {% endblock %}extends标签必须是子模板的第一个标签block标签定义可以被覆盖的区块。父模板里block中的默认内容在子模板没有覆盖相应block的时候生效。这样可以做到有一个统一骨架每个页面细节自定义的效果。include标签用于引入子模板片段{% include common/pagination.html %}include和extends的区别在于extends是继承关系一个模板只允许一个父模板include是组合关系一个页面可以多次引入不同的局部模板片段。还有一个常用的url标签它根据URL配置里的name参数反向生成URL路径避免在模板里硬编码链接# urls.py path(books/int:pk/, views.book_detail, namebook_detail),模板里使用a href{% url book_detail book.pk %}查看详情/a如果URL配置发生调整只要name不变模板里不需要改动。这个标签在做项目重构时能省下大量时间。static标签则用于生成静态文件路径{% load static %} link relstylesheet href{% static css/style.css %}注意第一行的{% load static %}不能省略这是加载static模板标签库的声明不过Django 3.0以后内置模板里static会默认可用。{% load static %}这句写了也没关系。3.4 模板语法的执行流程与常见误区深入理解模板的执行机制能帮助排查一些诡异的问题。模板渲染的步骤大致是Django加载模板文件解析成模板对象渲染时传入的上下文Context变量会被收集到一个变量栈中模板里的变量通过名称去这个栈里查找。这个查找机制带来一个容易困惑的点在for循环里如果你循环变量名和外层某个变量名相同会覆盖外层的。比如context {book: 外层变量}模板里{% for book in books %} {{ book.name }} {% endfor %} {{ book }}循环结束后{{ book }}输出了什么答案是最后一个循环元素而不是外层变量。因为for循环结束后循环变量并不会因为作用域结束而消失它还在当前上下文里覆盖了同名的外层变量。这是我实际项目里踩过的坑在模板里循环变量名用了item结果模板底部想引用传进来的item对象输出却变成了循环里的最后一个元素。处理办法是在模板里尽量使用不冲突的变量名循环变量用book_item、article_item这类有区分的命名或者循环里用as关键字把循环结果暂存。模板里不能写Python表达式只有变量、过滤器、标签这三类基础能力。部分新手在模板里写{{ request.user.is_authenticated and request.user.is_staff }}想做个逻辑判断模板会报错。应该改为{% if request.user.is_authenticated and request.user.is_staff %}if标签支持and、or、not、in等运算符支持括号。模板语法的设计目标是保持展示层简单把复杂的逻辑放在视图层处理。4. 实战搭建一个图书管理小功能纸上谈兵讲再多理论不如把代码过一遍。下面用一个图书管理的小项目做演示把前面讲的模板语法、请求处理、响应返回全部串起来。这个项目的业务足够简单图书列表展示 新增图书表单提交但覆盖了Django开发中最核心的几块内容。4.1 项目初始化与配置假设Django已经安装好了Python环境准备好了。我用Django 3.2版本新版4.x也可以用基础语法基本没变。django-admin startproject library_project cd library_project python manage.py startapp books创建好应用之后第一步是去settings.py注册应用顺便配置templates目录和数据库这里用默认的SQLite就够了# settings.py INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, books, # 注册自己创建的应用 ] TEMPLATES [ { BACKEND: django.template.backends.django.DjangoTemplates, DIRS: [BASE_DIR / templates], APP_DIRS: True, OPTIONS: { context_processors: [ django.template.context_processors.debug, django.template.context_processors.request, django.contrib.auth.context_processors.auth, django.contrib.messages.context_processors.messages, ], }, }, ] STATIC_URL static/ STATICFILES_DIRS [BASE_DIR / static]APP_DIRS: True的意思是Django会在每个应用的templates子目录下查找模板文件。我习惯同时建一个项目级的templates目录放公共页面比如base.html所以DIRS也要配置。4.2 模型定义与数据核心在books/models.py里定义一个简单的Book模型from django.db import models class Book(models.Model): name models.CharField(max_length200, verbose_name书名) author models.CharField(max_length100, verbose_name作者) price models.DecimalField(max_digits6, decimal_places2, verbose_name价格) published_date models.DateField(verbose_name出版日期) class Meta: ordering [-id] def __str__(self): return self.name执行数据库迁移python manage.py makemigrations python manage.py migrate为了演示方便进python manage.py shell插入几条测试数据python manage.py shellfrom books.models import Book Book.objects.create(nameDjango入门指南, author张三, price59.90, published_date2024-01-15) Book.objects.create(namePython Web开发实战, author李四, price79.00, published_date2024-03-20)4.3 URL路由与视图函数设计在library_project/urls.py里引入书的应用路由from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(books/, include(books.urls)), ]在books/urls.py里定义路由from django.urls import path from . import views urlpatterns [ path(, views.book_list, namebook_list), path(create/, views.book_create, namebook_create), ]视图函数是重头戏book_list处理GET请求展示列表数据book_create需要同时处理GET展示表单页和POST接收表单提交from django.shortcuts import render, redirect from django.http import JsonResponse from django.views.decorators.http import require_http_methods from .models import Book from .forms import BookForm def book_list(request): books Book.objects.all() return render(request, books/list.html, {books: books}) require_http_methods([GET, POST]) def book_create(request): if request.method POST: form BookForm(request.POST) if form.is_valid(): form.save() return redirect(book_list) else: form BookForm() return render(request, books/create.html, {form: form})这里用了一个叫BookForm的东西它其实是Django的ModelForm。用表单可以自动化处理字段校验、错误提示、CSRF令牌验证比自己手动request.POST.get()然后逐个校验要省事得多也安全得多。在books/forms.py里定义from django import forms from .models import Book class BookForm(forms.ModelForm): class Meta: model Book fields [name, author, price, published_date] widgets { published_date: forms.DateInput(attrs{type: date}), }4.4 模板文件编写项目级templates/base.html作为公共骨架{% load static %} !DOCTYPE html html langzh-CN head meta charsetUTF-8 title{% block title %}默认标题{% endblock %}/title link relstylesheet href{% static css/style.css %} /head body nav a href{% url book_list %}图书列表/a a href{% url book_create %}新增图书/a /nav main {% block content %}{% endblock %} /main /body /htmlbooks/templates/books/list.html{% extends base.html %} {% block title %}图书列表{% endblock %} {% block content %} h1图书列表/h1 {% if books %} table border1 cellpadding8 cellspacing0 tr thID/th th书名/th th作者/th th价格/th th出版日期/th /tr {% for book in books %} tr td{{ book.id }}/td td{{ book.name }}/td td{{ book.author }}/td td¥{{ book.price }}/td td{{ book.published_date|date:Y-m-d }}/td /tr {% endfor %} /table {% else %} p暂时没有图书数据。/p {% endif %} {% endblock %}books/templates/books/create.html{% extends base.html %} {% block title %}新增图书{% endblock %} {% block content %} h1新增图书/h1 form methodpost {% csrf_token %} {{ form.as_p }} button typesubmit保存/button /form {% endblock %}这里有个关键细节form表单里那一行{% csrf_token %}必须保留。没有这行提交POST表单时Django会返回403。这个标签会在表单里渲染一个隐藏的csrfmiddlewaretoken输入框值是一串随机令牌。Django的CsrfViewMiddleware在接收POST请求时会验证这个令牌防止跨站请求伪造攻击。4.5 代码运行效果与请求链路回溯在项目根目录执行python manage.py runserver浏览器访问http://127.0.0.1:8000/books/会看到图书列表页面。访问http://127.0.0.1:8000/books/create/填完表单点保存POST请求发出后经过CSRF验证、表单校验然后重定向回列表页能看到新增的图书记录出现在列表里。把这条链路的每个环节再对照一遍浏览器访问/books/路径发出了GET /books/请求Django的URL路由通过path(, ...)匹配到book_list视图视图函数查询Book.objects.all()拿到所有图书的QuerySetrender函数把books变量放入模板上下文渲染books/list.html模板引擎在{% for book in books %}循环里逐条输出数据通过{{ book.name }}等变量访问每条记录字段渲染完成的HTML字符串包装进HttpResponse返回给浏览器这个链路理解透了Django开发的大半个流程就已经在掌握之中了。5. 常见问题与排查技巧实录最后这部分把我做Django项目时踩过的坑、被问得最多的问题整理成速查表。这些问题分散在不同项目里反复出现过每一条背后都有一个真实的故事。5.1 请求处理类问题问题现象可能原因解决方案request.POST.get(name)返回None前端发送的是JSON数据不是表单编码使用json.loads(request.body)解析POST请求返回403提示CSRF验证失败表单或请求里缺少csrftoken模板表单加{% csrf_token %}AJAX请求在请求头加X-CSRFTokenrequest.GET.get(page)拿到的是字符串不是数字GET参数本来就是字符串转换类型int(request.GET.get(page, 1))注意捕获ValueError上传文件后request.FILES为空没有设置表单enctypemultipart/form-data表单加上enctypemultipart/form-data属性URL带中文参数时视图拿到乱码编码问题前端用encodeURIComponent编码后端用quote/unquote处理或用Django自带处理CSRF这一条值得多说一句。前后端分离项目里前端用Vue或小程序发POST请求没法像模板表单那样直接渲染csrfmiddlewaretoken隐藏字段。常见做法是后端提供一个接口读取Cookie里的csrftoken前端在每次请求时把它放进请求头发送过来。Django的CsrfViewMiddleware验证逻辑是优先检查请求头X-CSRFToken里的值是否与Cookie里的csrftoken匹配匹配则通过验证否则再检查POST表单里的csrfmiddlewaretoken字段。所以前端用axios可以这样写axios.defaults.headers.common[X-CSRFToken] getCookie(csrftoken);5.2 响应结果类问题问题现象可能原因解决方案JsonResponse返回中文变成\uXXXX默认ensure_asciiTrue设置json_dumps_params{ensure_ascii: False}直接返回列表给JsonResponse报TypeError默认只接受字典传入safeFalse接口超时且无日志视图内某个数据库查询死锁或外部请求阻塞检查数据库慢查询外部HTTP请求加超时时间下载文件中文名乱码Content-Disposition里中文没编码用urllib.parse.quote处理文件名前端拿不到响应头里的自定义字段跨域时没有暴露该响应头服务端设置Access-Control-Expose-Headers: X-Custom-Header5.3 模板渲染类问题问题现象可能原因解决方案{{ user.name }}输出为空变量名拼写错误或user里没有name键/属性在视图里打印context确认键名模板调试时用{% debug %}标签页面出现script标签源码不执行Django对变量输出做了HTML转义这是安全机制确认内容是可信的用{{ contentfor循环里用book.name取不到值循环变量名和上下文变量名冲突检查循环变量是否被覆盖改变量名{% block content %}里的内容没显示子模板里block名写错或没有{% extends %}确认父模板和子模板的block名称完全一致{% extends base.html %}报错找不到模板TEMPLATES配置里DIRS没配或模板放错位置把base.html放在templates目录下确认路径这里特别提一下调试模板问题的技巧。Django模板变量解析失败不会报错而是输出空字符串这个特性对新手很不友好。我的排查经验是在视图里把传入模板的context打印出来看一眼。或者用Django的{% debug %}模板标签在页面底部输出所有上下文变量一眼就能看到有没有你要的那个变量、变量名是不是拼错了。5.4 静态文件加载不出来问得最多的问题之一就是样式加载不了。开发环境下出现这个问题的原因基本是这么几个settings.py里STATIC_URL没配置模板里没写{% load static %}static目录下文件路径拼错没有执行python manage.py collectstatic这个在生产环境才需要开发模式下runserver会自动从应用目录下的static子目录和STATICFILES_DIRS指定的目录寻找静态文件。我的目录结构一般是library_project/ library_project/ settings.py static/ css/ style.css books/ static/ books/ js/ main.js templates/ base.html模板里这样引用{% load static %} link relstylesheet href{% static css/style.css %}记住{% static %}标签生成的是URL路径比如/static/css/style.css它背后映射到静态文件目录但不等于直接拼接STATICFILES_DIRS里的路径。调试时可以先用浏览器直接访问http://127.0.0.1:8000/static/css/style.css如果能打开就说明静态文件本身没问题问题大概率出在模板引用上。5.5 排查工具与习惯做完一个Django接口或者页面我习惯在浏览器开发者工具里看一遍完整请求网络面板里看请求URL、请求方法、状态码、请求头、响应体。这一步能快速判断问题是出在前端还是后端。比如接口返回了500响应体里往往会有Django的HTML错误页面展开能看到堆栈信息定位问题很快。后端这边开发时DEBUGTrue时Django会提供详细的错误页面包含异常堆栈、SQL语句、上下文变量基本等于一个免费的调试器。但生产环境必须把DEBUGFalse不然会泄露代码路径、配置信息。我自己还有一个习惯在项目里安装django-debug-toolbar开发模式下页面侧边会显示一个调试工具条能看到所有SQL查询、请求头、模板渲染时间等信息排查数据库N1查询和慢接口特别有用。写在最后Django的模板语法、请求与响应这三块表面上看是三个独立的知识点实际是同一个链路的不同环节。请求到达Django视图函数处理业务逻辑要么用模板把数据渲染成HTML页面返回要么用JsonResponse把数据打包成JSON返回给前端。理解了这个链路的全貌无论你是做服务端渲染的传统Django项目还是做前后端分离的全栈项目都能得心应手。我在实际项目中最大的体会是写视图函数之前先想清楚前端到底需要什么。如果是页面跳转用render渲染模板如果是数据交互用JsonResponse返回结构化的JSON如果需要先处理再跳转用redirect。想清楚这个再动手代码会简洁很多。还有一个用了很久的小技巧视图函数的逻辑尽量不要写得太长POST和GET分支分开处理校验逻辑尽量用Django Form或Serializer封装起来这样代码的可维护性会好很多。这套思路从我最早用Django写个人博客到现在做企业级的全栈项目一直都适用。
