用Django写过正经项目的人，回头再看官网那个投票教程，十有八九都会心一笑。这个项目看似简单，却把Django最核心的MTV模式、ORM操作、模板渲染和表单处理全部串了一遍。我这些年带过不少新人，也帮人排查过无数个从投票应用起步的坑，说实话，能把这个小项目彻底吃透，后面写什么业务系统都不虚。

很多人觉得投票应用太小儿科，不就是两个表、几个页面的事吗？实际上，它麻雀虽小五脏俱全。从数据模型的设计、数据库迁移，到admin后台的注册、通用视图的改写，再到表单的POST处理和CSRF防护，每一环都是Django开发绕不开的必修课。我见过太多人照着教程敲一遍就以为自己会了，结果一换业务场景就卡壳。所以这篇文章我不会简单复述官方文档，而是把我实际踩过的坑、总结出来的最佳实践、以及每一步背后的为什么都掰开揉碎讲清楚，目标是让你看完之后，不只能跑起来，还能真正理解这套框架的运转逻辑，并且知道出了问题该怎么排查。

这篇文章适合谁？刚学完Python基础、想接触Web框架的新手，或者已经能写点Django但理解停留在“照抄能用”层面的同学，都值得花半小时完整读一遍。有经验的开发者也可以直接跳到第6部分，看看我整理的常见问题排查表，顺手查漏补缺。

1. 整体设计思路：为什么投票应用是最好的Django入门项目

1.1 投票应用的技术覆盖面有多广

先把这个项目到底涉及多少知识点摊开来看。一个标准的投票应用，至少要包含两个数据模型：问题（Question）和选项（Choice）。问题有文本内容和发布日期，选项有文本内容和得票数，选项隶属于某个问题。这直接对应着Django的ORM模型层，你不用写一行SQL，就可以完成建表、增删改查、关联查询。

然后是URL路由。用户访问首页看到问题列表，点进某个问题看到选项，提交投票后看到结果页。这三个页面分别对应三个视图函数和三条URL规则。这里面有动态参数的传递、有模板的渲染、有重定向和反向解析，还有处理POST请求和CSRF验证。你会发现，整个Web开发最核心的请求-响应循环，在这一个小项目里全部走通了。

更不要说Django自带的admin后台。你只要在admin.py里注册模型，就能得到一个可以增删改查数据的后台界面，这在很多企业级项目里都是直接投入生产使用的功能。投票应用在教程里通常会把admin作为“顺带一提”的部分，但我会告诉你，admin远不止“顺带”这么简单，它背后是Django极其强大的ModelAdmin体系。

最后，当应用跑起来之后，你还要面对静态文件的加载、模板的继承与复用、数据库迁移的版本管理。这些全都是实际开发中的家常便饭。所以如果你把投票应用只是当作“练习题”就太小看它了，它其实是一个浓缩的、完整的Django开发流程样本。

1.2 为什么我推荐你手动跑一遍官方流程而不是直接用脚手架

很多新手习惯了一个命令生成项目，但这恰恰是问题所在。django-admin startproject和python manage.py startapp这两条命令产生的只是骨架，整个框架的血肉是你一行一行填进去的。手动创建文件、手动注册app、手动配置路由，这个过程虽然繁琐，但能让你把每一个文件的角色、每一个配置项的用途记在脑子里。

举个例子，很多人搞不清楚INSTALLED_APPS是干什么的，如果你只是敲命令生成项目，你可能永远不会往这个列表里添加自己的应用，自然也就不知道为什么明明写了模型却提示Table 'polls_question' doesn't exist。只有当你亲手把自己的应用加进这个列表，再观察Django的迁移命令从扫描无到有、从无到有地创建表，你才真正理解“Django的应用是一个可插拔的组件”这句话的分量。

所以这篇博文里，我会故意保留那些看起来有点重复、有点琐碎的手动步骤，并且解释每一条命令背后发生了什么。这是经验和教训换来的：跳过细节的人，后来都回来补课了。

2. 环境准备与项目初始化：先把地基打牢

2.1 虚拟环境与Python版本选择

先说Python版本。Django 4.x和5.x都要求Python 3.10起步，如果你还在用Python 3.8或者更老，建议先升级。我在实际项目中遇到过太多次因为版本不匹配导致的诡异报错，比如ImportError: cannot import name 'TextChoices' from 'django.db.models'，多半就是Django版本和Python版本不对应造成的。

强烈建议从一开始就用虚拟环境。python -m venv venv这行命令建出来的环境，干净、隔离，不会污染系统的Python。Windows下启动是venv\Scripts\activate，Linux和macOS下是source venv/bin/activate。我见过有人不建虚拟环境，直接用全局Python装Django，结果系统里同时存在Django 2.2和Django 4.1，最后项目跑起来各种报错，查了半天才发现是Python环境串了。

虚拟环境激活之后，安装Django只需要一条命令：

pip install django

安装完可以用python -m django --version验证版本。这一步虽然简单，但我见过有人在虚拟环境里装好了，却因为终端没切换到虚拟环境，敲django-admin命令时报command not found。记住：虚拟环境激活状态下，pip和python都指向环境内部的解释器，命令行工具也在环境里。

2.2 创建项目和应用：startproject与startapp的职责划分

安装好Django后，先创建项目再创建应用。这里的项目和应用是两层概念，很多新手分不清，我多说几句。项目（project）是整个站点的配置集合，它管理的是全局的URL配置、settings配置、应用列表、静态文件目录等，相当于公司的行政部。应用（app）是具体的功能模块，比如投票应用、博客应用、用户系统，相当于公司里的业务部门。一个项目可以包含多个应用，一个应用也可以被多个项目复用。

创建项目的命令是：

django-admin startproject mysite

这会生成一个mysite目录，里面有一个manage.py和同名子目录。真正操作项目的人，都是在manage.py所在目录执行命令的，django-admin只在创建项目时用一次，之后的工作都交给manage.py。因为manage.py会自动读取当前目录的settings配置，而django-admin是全局的、不知道你的settings在哪。

接着进入项目目录，创建投票应用：

python manage.py startapp polls

这会在项目根目录生成一个polls目录，里面自动带好了models.py、views.py、admin.py、apps.py、migrations目录等文件。注意一点：startapp执行完之后，这个应用并没有真正变成项目的一部分。你还得去mysite/settings.py里找到INSTALLED_APPS列表，把'polls'加进去，Django才会在后续的命令中扫描这个应用。

# mysite/settings.py INSTALLED_APPS = [ 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles', 'polls', # 手动加上这一行 ]

这一步我非常想强调，因为新手在这个问题上栽跟头的概率极高。INSTALLED_APPS里的每一个应用，Django启动时都会去初始化它，包括读取模型、注册admin、加载模板等。你不加'polls'，Django对polls应用就完全无感，后面你写模型、写视图、写URL，都会遇到各种神秘问题。最典型的就是运行迁移时报Unable to detect migration state，或者Table not found，根本原因往往就是这里少了一步。

2.3 数据库配置：默认SQLite到底够不够用

投票应用教程默认的数据库是SQLite，配置文件在settings.py里的DATABASES。SQLite是一个文件型数据库，不需要额外的服务，对于学习和原型验证完全够用。但到了生产环境，我建议换成PostgreSQL或MySQL。理由很简单：SQLite在高并发写入场景下容易出现数据库锁异常，而且不适合多个进程同时写。

不过，这篇博文里我们就用SQLite。原因是你不需要安装任何额外的东西，也不需要配置用户名密码。Django会自动创建一个db.sqlite3文件，整个数据库就存在于这个文件中。理解这一点对排查问题很有帮助：如果你发现数据库里的数据不对，直接删掉db.sqlite3再重新迁移，就能重置到初始状态，这在开发阶段是很常用的操作。

3. 建模与数据库迁移：Django ORM的精髓从这里开始

3.1 设计Question和Choice模型

投票应用的核心模型是Question和Choice。打开polls/models.py，默认内容是一个from django.db import models的导入。我们要在这里定义两个模型类：

from django.db import models class Question(models.Model): question_text = models.CharField(max_length=200) pub_date = models.DateTimeField('date published') def __str__(self): return self.question_text class Choice(models.Model): question = models.ForeignKey(Question, on_delete=models.CASCADE) choice_text = models.CharField(max_length=200) votes = models.IntegerField(default=0) def __str__(self): return self.choice_text

这里有几个点要重点解释。第一个是ForeignKey。Choice和Question是多对一的关系，一个问题下可以有多个选项，每个选项只属于一个问题。在数据库中，Django会把外键存成question_id字段。第二个是on_delete=models.CASCADE，这个参数告诉Django：如果关联的问题被删除了，那么它的所有选项也一并删除。这是新版Django的硬性要求，不写会直接报错，老版本可以不写，但默认行为是级联删除，现在强制你要明确表达意图。

第三个是__str__方法。别小看这个魔术方法，它的作用远不止在admin后台显示好看。当你在视图里打印对象、在错误日志里看到对象的表现形式时，都会用到它。如果不定义，所有对象在日志里都显示为Question object (1)，调试起来完全没有头绪。我处理过很多次报错现场，反复确认报错对象是谁，就是因为模型里没写__str__。这是最基础也最值得养成的习惯。

关于DateTimeField，这里传入的第一个位置参数'date published'是给admin后台用的字段显示名，算是人性化的附加信息。你可以传也可以不传，但传了之后后台的标签更友好，算是一点点细节。

3.2 迁移流程：makemigrations与migrate的配合逻辑

模型定义好之后，需要把它变成数据库里的真实表。这个过程分两步走。第一步是生成迁移文件：

python manage.py makemigrations polls

运行之后，Django会在polls/migrations目录下生成一个类似0001_initial.py的文件。这个文件里的内容其实就是Python代码，描述了你刚刚定义的模型结构。你可以打开看一眼，理解一下Django是怎么把你写的模型类翻译成数据库操作指令的。这一步是整套流程里最优雅的部分：模型是代码，迁移也是代码，数据库的schema被完全代码化了，版本管理变得顺理成章。

第二步是真正应用迁移：

python manage.py migrate

这行命令会把尚未应用到数据库的所有迁移文件全部执行一遍。注意，makemigrations是生成迁移，migrate是执行迁移，两者职责不同。我见过有人把这两条命令混为一谈，反复敲migrate却忘记先makemigrations，结果模型改了数据库没反应，还以为Django坏了。

如果你修改了模型，比如给Question增加了字段，流程也是一样的：先makemigrations生成新的迁移文件，再migrate应用。Django的迁移系统会自动检测到模型的变更，生成增量的迁移文件，真正做到schema的版本控制。这在多人协作时尤其重要。

3.3 通过admin后台管理数据：快速上手与常见坑点

Django的admin后台是我最喜欢的功能之一，因为它几乎是零成本给你提供了一个完整的管理界面。要使用它，需要两个步骤。第一步确保django.contrib.admin在INSTALLED_APPS里、admin的URL在urls.py里。默认生成的工程已经配好了。第二步是创建超级管理员账户：

python manage.py createsuperuser

按照提示输入用户名、邮箱（邮箱其实可以不填，直接回车跳过）、密码。然后启动开发服务器：

python manage.py runserver

浏览器访问http://127.0.0.1:8000/admin/，登录之后看到的只有默认的用户和组管理，没有我们的投票应用。这是因为你还没有在admin.py里注册模型。打开polls/admin.py：

from django.contrib import admin from .models import Question, Choice admin.site.register(Question) admin.site.register(Choice)

注册之后再刷新后台页面，就能看到Question和Choice的管理入口了。点击进去可以增删改查，整个数据管理体验堪比很多收费系统的后端。

这里有一个很常见的坑：有人在admin.py里写了注册代码，但后台刷新死活不显示。检查顺序一般是：模型是否定义正确、admin.py里是否导入了模型、INSTALLED_APPS里是否注册了应用。如果这三项都对，那再看一眼你是不是忘了重启开发服务器。Django的开发服务器默认开了自动重载，修改代码会自动重启，但如果你的代码有语法错误导致启动失败，页面会直接报错而不是展示后台。

另外我建议顺便在admin.py里做一点小小的优化。默认情况下，Choice的后台列表看起来有点简陋，如果你想看到更多信息，可以用ModelAdmin类：

class ChoiceInline(admin.TabularInline): model = Choice extra = 3 class QuestionAdmin(admin.ModelAdmin): fieldsets = [ (None, {'fields': ['question_text']}), ('Date information', {'fields': ['pub_date'], 'classes': ['collapse']}), ] inlines = [ChoiceInline] admin.site.register(Question, QuestionAdmin)

这样在编辑Question的时候，可以直接在同一个页面里添加三个选项（extra = 3控制额外空白选项的数量），不用再到Choice页面里去逐条添加。生产环境中管理多表结构时，这个TabularInline功能非常实用，它能让你的后台体验上一个台阶。

4. 编写视图与路由：打通请求-响应的主链路

4.1 从HttpRequest到HttpResponse：视图函数的工作机制

Django的视图函数，本质上就是一个接收HttpRequest对象、返回HttpResponse对象的普通Python函数。你在浏览器里输入一个URL，Django会按照urls.py里的路由规则，找到对应的视图函数，调用它，把返回值拼成HTTP响应发回浏览器。这个过程听起来简单，但有几个细节值得展开。

先看一个最简单的视图。打开polls/views.py，写入：

from django.http import HttpResponse def index(request): return HttpResponse("Hello, world. This is the polls index.")

然后在polls目录下新建urls.py：

from django.urls import path from . import views urlpatterns = [ path('', views.index, name='index'), ]

最后修改项目的mysite/urls.py：

from django.urls import include, path urlpatterns = [ path('polls/', include('polls.urls')), path('admin/', admin.site.urls), ]

这里最重要的一步是include。我见过不少新手把应用的路由直接一股脑写进项目的urls.py里，一开始没问题，但应用一多、路由一多，项目根URL配置就成了一锅粥。正确的做法是每个应用维护自己的urls.py，项目根配置只负责用include把应用的路由挂载进来。这样应用与项目解耦，代码的可维护性直线上升。

path函数里的name='index'是路由的命名。为什么要命名？因为后面在模板里或者视图中做重定向时，你可以用名字来引用URL，而不是硬编码URL字符串。如果你在代码里到处写死/polls/，哪天URL变了，你就要全局搜索替换，而用了name之后只需要在urls.py里改一处。这个习惯从一开始就要养成。

4.2 动态路由参数：捕捉问题ID

投票应用的详情页URL是/polls/1/，这个1是Question的主键id。在视图里，你需要拿到这个id，根据它从数据库查出来对应的Question对象。还是先写视图：

from django.shortcuts import get_object_or_404, render from .models import Question def detail(request, question_id): question = get_object_or_404(Question, pk=question_id) return render(request, 'polls/detail.html', {'question': question})

注意视图函数的第二个参数叫question_id，这个参数名必须和urls.py里path的尖括号里写的名字一致。路由配置是：

path('<int:question_id>/', views.detail, name='detail')

<int:question_id>这段语法表示：接受一个整数，把它作为关键字参数question_id传给视图函数。Django内置了多种转换器，比如<str:xxx>接受任意字符串但不含斜杠，<uuid:xxx>接受UUID。如果你需要匹配更复杂的格式，还可以自定义转换器。

这里我用的是get_object_or_404而不是Question.objects.get(pk=question_id)。两者的区别在于：当id不存在时，get会抛出DoesNotExist异常，如果你不捕获，就会导致500错误；而get_object_or_404会在对象不存在时直接返回HTTP 404页面，这对用户更友好，也更符合语义。从代码简洁度上看，get_object_or_404一行搞定，不用写try/except，代码清爽很多。

4.3 模板系统与上下文渲染：Django模板不是字符串拼接

Django的模板系统是它的一大特色。它允许你在HTML文件中嵌入模板语法，比如{{ 变量 }}和{% 标签 %}，然后由视图传入一个字典（称为上下文），模板负责把字典里的数据渲染成最终的HTML。

按照惯例，Django会在每个应用下寻找templates目录。所以你先在polls目录下创建templates/polls/子目录，再在里面放detail.html。为什么要多一层polls目录？因为Django的模板查找机制会把所有应用的templates目录合并成一个集合来查找。如果两个应用各有一个index.html，模板引擎根本分不清该用哪个。加上应用名前缀作为命名空间，是官方推荐的做法，也是防止冲突的标准方案。

写一个最简单的detail.html：

<h1>{{ question.question_text }}</h1> <ul> {% for choice in question.choice_set.all %} <li>{{ choice.choice_text }}</li> {% endfor %} </ul>

这里的question.choice_set.all可能让新手困惑。choice_set是Django为ForeignKey反向关系自动生成的属性名。你在Choice模型上定义了一个指向Question的外键，那么Django就自动给Question对象加上一个choice_set属性，用来获取“属于这个问题的所有Choice对象的查询集合”。要注意，这个属性名默认是小写模型名_set，如果你想换个更语义化的名字，可以在外键里指定related_name：

class Choice(models.Model): question = models.ForeignKey(Question, on_delete=models.CASCADE, related_name='choices')

这样在模板里就可以写{{ question.choices.all }}，语义清晰得多。关于反向关联的命名，算是一个设计习惯，项目稍大之后会体会到它的好处。

4.4 模板继承：用base模板统一页面结构

只做一个页面的时候看不出来，页面一多你就会发现，列表页、详情页、结果页共享着同一套页面骨架：同样的<head>、同样的CSS引入、同样的导航栏。如果没有模板继承，每页都写一遍这些公共内容，改一次样式就要全局改文件，纯体力劳动。

Django的模板继承思路很清晰。先建一个templates/base.html：

<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>{% block title %}Polls{% endblock %}</title> </head> <body> {% block content %} {% endblock %} </body> </html>

然后在子模板里这样做：

{% extends 'base.html' %} {% block title %}问题详情{% endblock %} {% block content %} <h1>{{ question.question_text }}</h1> ... {% endblock %}

{% extends %}告诉模板引擎“我以base.html为骨架”，{% block %}就是在骨架中填充或覆盖对应区域的内容。如果某个子页面不想覆盖某个块，就不用写同名的block，base里默认内容就会生效。

这个技巧在实际开发中用到极致之后，你的模板会非常有层次：基础模板定义大框架，多个子模板各自填充内容，甚至可以在子模板里再嵌套子模板。很多企业项目里，整站的面包屑、页脚、侧边栏都是通过这种继承机制搭建的。

5. 表单处理与投票逻辑：POST请求、CSRF与业务更新

5.1 POST表单与CSRF防护：Django为什么强制要求模板加csrf_token

投票的核心动作是用户点击某个选项，提交投票，然后系统把票数加一。这个动作会对数据库进行写入操作，按照HTTP规范，应该使用POST方法，而不是GET。GET请求会被浏览器缓存、爬虫抓取、留在历史记录里，不适合做修改类操作。

在detail.html里添加一个表单：

<form action="{% url 'polls:vote' question.id %}" method="post"> {% csrf_token %} {% for choice in question.choices.all %} <input type="radio" name="choice" id="choice{{ forloop.counter }}" value="{{ choice.id }}"> <label for="choice{{ forloop.counter }}">{{ choice.choice_text }}</label><br> {% endfor %} <input type="submit" value="投票"> </form>

这里的{% csrf_token %}是新手最容易忽略、也最容易报错的地方。如果不加这个标签，提交表单时Django会直接返回403 Forbidden错误，页面上一堆英文“CSRF verification failed”。很多人第一次遇到这个问题时一脸懵，以为是自己代码Bug，其实只是少加了一个模板标签。

CSRF（跨站请求伪造）的原理是：攻击者可以在自己的网站上构造一个表单，诱导用户提交，从而利用用户的登录状态向目标网站发送恶意请求。Django的防护手段是在返回表单页面时种下一个随机的token，并把token同时放在表单里；提交请求时，Django会校验提交的token和session里的token是否一致，不一致就拒绝请求。这中间还有同源校验等细节，但核心机制就是这样。

5.2 编写vote视图：更新数据的三种写法与区别

接下来写vote视图。这里的核心逻辑是：从POST数据里取出用户选的选项id，把它对应的Choice对象的votes字段加一。官方教程里的写法是：

from django.http import HttpResponseRedirect from django.shortcuts import get_object_or_404, render from django.urls import reverse from .models import Choice, Question def vote(request, question_id): question = get_object_or_404(Question, pk=question_id) try: selected_choice = question.choices.get(pk=request.POST['choice']) except (KeyError, Choice.DoesNotExist): return render(request, 'polls/detail.html', { 'question': question, 'error_message': "你没有选择任何选项。", }) else: selected_choice.votes += 1 selected_choice.save() return HttpResponseRedirect(reverse('polls:results', args=(question.id,)))

这段代码有几个点值得细看。

首先是request.POST['choice']。request.POST是一个类似字典的对象，如果用户没有选择选项就提交，这个键不存在，会抛出KeyError。如果你的模板里radio的name属性不是choice，这里也会KeyError。所以这个try/except不是多余的，它是在处理用户输入不完整的情况。

其次，更新投票数这一行代码：

selected_choice.votes += 1 selected_choice.save()

在Python层面，votes += 1只是把内存中这个对象的属性加一，并不等于修改了数据库。只有执行.save()之后，Django才会把内存中的修改同步回数据库。这一点如果不理解，你会经常遇到页面显示数据变了、刷新后又变回去的诡异现象——其实是你改了内存里的对象，忘了保存。

如果你想写得更专业，可以用Django的F表达式来原子地更新字段：

from django.db.models import F selected_choice.votes = F('votes') + 1 selected_choice.save()

F表达式的作用是把数值加一这个操作下放到数据库层面执行，而不是先取出来、在Python里加、再存回去。在高并发的场景下，用F表达式能避免所谓的“竞态条件”：两个请求同时读取votes=10，各自加一后存回，正常情况下会得到12，但如果不加锁或不用F表达式，可能最终只加了一次。使用F表达式之后，数据库会在这一行数据上做原子递增，不会丢更新。这个细节非常值得记下来，以后做计数器、库存扣减都会用到。

5.3 重定向、reverse和命名空间URL：为什么不在视图里硬编码URL

vote视图的最后一步是重定向到结果页，这里用的是：

return HttpResponseRedirect(reverse('polls:results', args=(question.id,)))

为什么不直接写HttpResponseRedirect('/polls/1/results/')呢？因为如果哪天你改了URL路径，比如把polls改成了survey，那你得去视图中把所有硬编码的URL全改一遍，稍不留神就会漏。而reverse('polls:results', args=(question.id,))会去urls.py里找名为results的路由规则，动态地拼出当前实际的URL。这就是“不要重复自己”原则在URL层面的体现。

注意'polls:results'这个格式。冒号前面是URL命名空间，冒号后面是路由名字。命名空间是你在urls.py里定义的：

app_name = 'polls' urlpatterns = [ path('', views.index, name='index'), path('<int:question_id>/', views.detail, name='detail'), path('<int:question_id>/results/', views.results, name='results'), path('<int:question_id>/vote/', views.vote, name='vote'), ]

app_name = 'polls'这一行非常重要。没有它，你可以在模板里直接写{% url 'results' %}；有了它，模板里就要写{% url 'polls:results' %}。为什么要引入这层命名空间？因为当一个项目里有两个应用，各自都有一个名为results的URL路由时，不带命名空间的反正解析会撞车，Django根本不知道你指的是哪个。加上命名空间，就彻底解决了这个冲突问题。

模板中的{% url 'polls:vote' question.id %}和视图中的reverse本质是一个机制，都是通过路由名字反向解析出真实URL。我提醒一句：路由的name一定不能重名，尤其在一个应用的所有URL中，任何两个路由的name都不能相同，否则Django启动时就会报URL name 'xxx' is not unique。

5.4 结果页视图与通用视图：代码量骤减的正确姿势

结果页的逻辑很简单：拿到Question对象，渲染一个模板展示每个选项和票数。常规写法是：

def results(request, question_id): question = get_object_or_404(Question, pk=question_id) return render(request, 'polls/results.html', {'question': question})

写到这里你可能会发现，detail和results的结构几乎一模一样：都是根据id拿对象，然后渲染模板。Django也意识到了这一点，提供了一组通用视图，把这种常见模式封装成了类。用通用视图改写后的代码是这样的：

from django.views import generic from .models import Question, Choice class IndexView(generic.ListView): template_name = 'polls/index.html' context_object_name = 'latest_question_list' def get_queryset(self): return Question.objects.order_by('-pub_date')[:5] class DetailView(generic.DetailView): model = Question template_name = 'polls/detail.html' class ResultsView(generic.DetailView): model = Question template_name = 'polls/results.html'

这是什么魔法？ListView自动从数据库查询model指定的所有对象列表，并把它传递给模板；DetailView则是根据URL里的主键来定位单条对象。关键在于模板中引用上下文的变量名。ListView默认的上下文变量名是object_list，DetailView默认是object。在用ListView时，我建议像上面一样显式设置context_object_name，比如设成latest_question_list，这样模板里的变量名就有了业务含义，可读性好很多。

最后把URL改成使用视图类：

path('', views.IndexView.as_view(), name='index'), path('<int:pk>/', views.DetailView.as_view(), name='detail'),

注意，DetailView期望URL参数的名字是pk而不是question_id，所以urls.py里尖括号中的参数名要相应改成pk。这就是为什么有的项目中URL显示是<int:pk>。知道这个转换关系，排查问路相关的报错能省很多时间。

我给你的建议是：初学阶段先老老实实写函数视图，理解每个步骤在干什么；等熟练了再迁移到通用视图，感受Django“约定优于配置”的设计哲学。两者都写一遍，你才算真正掌握这一段的全部内容。

6. 常见问题与排查技巧：那些年我帮人踩过的坑

6.1 迁移与数据库相关高频报错

投票应用虽然简单，但新手遇到报错的频率一点也不低。我整理了几个高频问题，每一个都是我亲眼见过、亲手处理过的真实案例。

最常见的是OperationalError: no such table: polls_question。看到这个报错，第一反应不是代码问题，而是数据库里根本没有这张表。原因一般有二：一是你还没来得及运行migrate，或者运行错了目录；二是你修改了模型但没有更新迁移，表结构对不上。解决办法是回到manage.py所在目录，依次执行makemigrations polls和migrate。如果数据库中已有部分脏数据，而你只是开发阶段，最省事的做法是删掉db.sqlite3文件，重新迁移。记住：这个操作会把所有数据清空，生产环境绝对不能用。

另一个高频问题是修改模型后迁移报错，提示You are trying to add a non-nullable field 'xxx' to 'xxx' without a default。这是因为你在已有数据的表中新增了一个不允许为空的字段，Django不知道旧记录的这一列该填什么。解决办法很简单：给字段加default值，或者设成null=True。如果你现在是一个测试环境，也可以直接删掉数据库重来。

6.2 URL路由匹配相关报错

NoReverseMatch是另一个高频报错，几乎每个Django新手都会遇到。它的意思是“反向解析URL失败了”，也就是Django在urls.py的所有路由里找不到你指定的name。检查步骤是这样：

先确认模板或视图里的路由名字写对了，拼写错误是最常见原因。然后确认app_name已经定义，但注意不要重复定义，比如你在两个文件里都写了app_name = 'polls'，后者会覆盖前者。接着确认urls.py中的path里确实有对应name的路由，有时你新建了视图却忘了在urls.py里添加路由。最后确认你引用的include路径正确，比如path('polls/', include('polls.urls'))，确保URL前缀和子路由拼接后的完整路径符合预期。

还有一个让人抓狂的问题：页面能访问但所有样式丢失，F12控制台报404。这通常不是代码问题，而是Django在开发模式下没有正确提供静态文件服务，或者你的HTML里静态文件路径写错了。在投票应用里，你可能会给页面加一点CSS，记得在settings.py里加：

import os STATIC_URL = '/static/'

然后模板里这样引用：

{% load static %} <link rel="stylesheet" href="{% static 'polls/style.css' %}">

6.3 表单相关的POST报错与常见疏漏

CSRF验证失败，除了没写{% csrf_token %}之外，还有一个常见场景是：你改了session的过期时间或者启用了cache存储session，导致token验证对应的session数据不一致。解决办法是检查SESSION_ENGINE配置，以及尝试清一下浏览器的Cookie再刷新页面。

还有一个看着很怪的问题：用户投完票之后点了浏览器后退按钮，再点提交，发现再次投票成功了，票数加了两次。这个本质上是HTTP/WEB浏览器行为的问题。你可以在vote视图里做防重复投票的设计：用session记录该用户已经投过的question.id。我见过有人在生产环境因为没有这种幂等设计，被刷票工具把票数冲到几百万。投票应用的业务特性天然容易被刷，如果你只是练习，至少心里有数；如果真要上线，除了用session做标识，还要考虑后台管理和数据校验的配合。

6.4 Django版本差异与兼容性注意事项

Django 2.x、3.x、4.x、5.x之间有一些细微差别，比如URL写法。Django 2.0及之后推荐用path，但对正则路由要用re_path。教程里一般用path，但你在网上看到的老代码可能还在用url方法，那是Django 1.x的写法，在Django 4.x和5.x上会直接报错。

另外django.conf.urls.url在旧版本教程里到处都是，如果你照着老教程敲代码，很可能遇到AttributeError: module 'django.conf.urls' has no attribute 'url'。解决办法是把url()改成re_path()或者path()。这个具体怎么改，取决于你要匹配的路由格式：纯字符串路径用path，正则表达式用re_path。

版本差异其实也提醒我们：看到一篇教程代码，先看它标注的Django版本，再决定要不要照着抄。我见过不少新人卡了很久，最后发现是教程太旧、语法过时导致的问题。

6.5 一个实测有效的完整排错流程

如果你遇到问题但不确定从哪排查，我建议按这个顺序来：

先看Django日志和开发服务器的终端输出，绝大多数错误会被直接打印在那里，带着完整的堆栈信息。然后看浏览器控制台，如果页面请求返回500，服务器端一般会有具体异常。看一眼settings.py里的DEBUG设置，如果DEBUG = False，Django会吞掉错误详情，只显示500页面，排错效率极低。开发阶段务必保持DEBUG = True。

然后核对基础配置：是否在INSTALLED_APPS注册了应用，urls.py是否用include正确引入，polls/templates目录结构是否多了或少了层级。再核对迁移：运行python manage.py showmigrations查看哪些迁移还没执行，未执行的用migrate补上。最后核对模板内容：是否有语法错误、变量名拼写是否正确、block是否重复等。

这套流程本身帮我解决过大量问题，也推荐给你。记住，排错的核心是缩小问题范围：先定位是配置问题、数据问题还是代码问题，再针对性地往下查。

7. 从投票应用到真实项目：几个值得做的扩展方向

如果你已经把投票应用完整跑通，并且理解了每一个环节的原理，恭喜你，你已经有能力往真实项目方向迈进了。但直接上大项目可能跨度太大，我建议复用这套知识，做几个小扩展。

第一个扩展是给投票应用加上用户登录认证。你可以用Django自带的django.contrib.auth框架，实现用户注册、登录、退出，然后把投票行为与用户关联。这比理论上强行设计一个用户系统的学习成本低很多，因为Django已经帮你把实现细节封装好了。你只需要理解request.user的含义、@login_required装饰器的用法。这个扩展做完，你的投票应用就具备了多用户参与的真实场景。

第二个扩展是把投票的结果数据用图表展示。Django后端返回JSON，前端用Chart.js或ECharts渲染柱状图/饼图。这里你会接触到JSON响应、API设计与前端联调的全过程。很多教程止步于模板渲染，但实际工作中，前后端分离才是最普遍的开发模式。投票应用可以作为你学习写接口的起点。

第三个扩展是引入django-rest-framework把投票应用改造成纯API后端。这是另一个很经典的教程项目：用DRF重写Question和Choice的序列化器，实现CRUD接口。你会学习到ViewSet、Router、权限控制等概念。这条路走下去，你已经具备写出一个可维护的后端API服务的能力了。

每个扩展都足够再写一篇长文，但核心思路是一致的：把投票应用当成一个“训练场”，从增删改查到认证鉴权，从页面渲染到前后端分离，逐步加深对Django生态的理解。我见过很多从Django官方教程起步的开发者，最终走向了不同的领域，有人转去做数据工程，有人深耕Web安全，有人专注于后端架构。你会发现，投票应用教给你的不只是Django，更是Web开发的基本规律。

回头再看那个简单的投票项目，我个人的体会是：真正难的不是代码怎么写，而是你有没有把每一步背后框架的设计意图想明白。为什么用POST而不是GET？为什么要CSRF token？为什么要反向解析URL？为什么要用F表达式？当你开始追问这些为什么，你就真正从一个“照着教程敲代码的人”变成了“理解框架的设计者”。这种思维方式的转变带来的收益，远远超过多学几个框架、多会几个函数。