1. 项目概述官方教程跑通之后真正的实战才刚刚开始如果你刚把 Django 官方教程里那个投票应用从头到尾做完可能会有一种微妙的错觉觉得自己已经会 Django 了。但等你打开浏览器看着那个勉强能用的后台和几个表单页面又会很快清醒——距离一个能真正上线的项目中间还隔着无数个“细节地狱”。这篇博文就是记录我完成官方教程之后继续用这个底子去做真实项目的全过程。包含了我是如何整理目录结构、怎么理解 QuerySet 的增删改查、如何给接口补上 token 认证以及最后怎么用 WebSocket 把后端数据实时推到浏览器前端。这篇内容适合两类人一类是刚做完官方教程、想继续往前走的新手另一类是写过一点 Django 但总觉得基础不扎实、想系统梳理一下查询和认证细节的同学。我会把每一步背后的理由也讲清楚而不是只丢结论。官方教程给的是骨架这篇文章补的是血肉。先说一个总体判断官方教程的投票应用虽然简单但它搭建的路是正路——MTV 分层、ORM 映射、模板渲染、Admin 后台、表单处理全都有了。问题在于教程把这些串得太顺导致你容易忽略很多设计上的取舍。而在真实项目里几乎每一步都要你亲自做决策。2. 整体设计思路先看懂官方教程在教什么再思考怎么改2.1 官方教程真正教会你的四件事不要小看这个投票应用。它把 Django 的使用链路完整走了一遍创建项目、创建应用、编写模型、迁移数据库、注册后台、写视图、配路由、用模板渲染数据、处理表单提交。这套链路就是你未来所有 Django 项目的基本盘。官方教程还有一个容易被忽略的细节它对 URL 命名使用了name参数在模板中用{% url %}反向解析路径——这个习惯很多人做项目时反而会丢掉喜欢硬编码 URL结果改路由之后满屏报错。另外教程里的self.question_text[:50]这类__str__魔方法写法也值得学到。后台列表页显示的不是对象内存地址而是有意义的描述文本全靠这个。我后来在真实项目里维护十几个模型每次都会庆幸当初养成了给模型写__str__的习惯。2.2 从 demo 到项目目录结构先重组跑完教程后我做的第一件事不是急着加功能而是重新检查项目根目录。官方教程默认生成的结构里polls应用和mysite项目配置放在同一层。小 demo 没问题但真实项目一般会调整成apps目录统一管理多个子应用再配一个common或utils目录放通用模块。我的做法是建一个apps文件夹把业务应用全部移进去然后在settings.py里加一行import sys from pathlib import Path BASE_DIR Path(__file__).resolve().parent.parent sys.path.insert(0, str(BASE_DIR / apps))这样INSTALLED_APPS里写user_app、blog_app就能直接识别不用写一长串相对路径。看起来是小改动但对后续项目扩展很关键。你要是用 PyCharm 打开项目记得把apps目录标记为 Sources Root不然 IDE 会提示找不到模块。2.3 视图层选型函数视图还是类视图官方教程用的是函数视图FBV写起来直观适合理解请求处理流程。但真实项目里我大量使用类视图CBV尤其是ListView、DetailView、CreateView这一组。核心原因是 CBV 把常见的 CRUD 流程抽象成了类属性代码量大幅减少。不过我的建议是新手时期先用函数视图写几个页面把手动获取数据、渲染模板、处理 POST 请求的完整流程走一遍。因为 CBV 封装太狠很容易出现“代码能跑但完全不知道发生了什么”的情况。等 FBV 手感有了再切 CBV 就会觉得是在简化工作而不是黑魔法。具体到一个页面怎么选我的习惯是需要自定义复杂业务逻辑、多步骤表单、依赖外部 API 的——用 FBV好调试。纯数据库读取、模板展示、权限控制简单的——用 CBV代码少且自带get_queryset扩展点。有同学说 CBV 不好调试其实django.views.generic的源码并不难读花半小时把View、TemplateView、ListView三个类看一遍你会打开新世界。3. 核心细节解析创建 app 的正确姿势与 settings 配置避坑3.1 一条命令背后发生了什么python manage.py startapp myapp是每个 Django 新手最先接触的命令之一。它会在当前目录下生成一个包含models.py、views.py、admin.py、apps.py、migrations/等文件的包结构。但很多人没注意到这个命令只是生成文件不会帮你注册到项目。你需要去settings.py的INSTALLED_APPS里手动添加应用名Django 才知道要同步这个 app 的数据表、读取它的模板和静态文件、加载它的路由。如果漏了这一步你migrate时会发现数据表没有创建python manage.py startapp生成的migrations/目录里也没有任何迁移记录——不是命令坏了是你根本没告诉项目这个应用的存在。另一个坑是 app 名称与 Python 包名冲突。我见过有人把一个内部业务应用命名为test结果导入test.py模块时和 Python 内置测试库撞车。遇到奇怪导入错误时先怀疑你的命名有没有撞标准库。3.2 settings.py 里最容易翻车的三个配置项第一是STATIC_URL和静态文件目录。官方教程只用了少量内联样式真实项目里 CSS、JS、图片都需要单独管理。推荐在项目根目录建static/在settings.py中配置STATIC_URL /static/ STATICFILES_DIRS [BASE_DIR / static]开发环境这样够了。部署时的collectstatic是另一个大坑后面会提。第二是TEMPLATES里的DIRS。虽然 Django 默认会去每个 app 下的templates/找模板但如果你想放全局模板比如base.html、通用 404 页面就要在DIRS里加上全局模板目录。否则模板继承时extends base.html会报找不到模板。第三是ALLOWED_HOSTS。本地开发写空列表没问题但一旦部署到服务器不把域名或 IP 加进去访问就会得到Bad Request (400)。这个报错新手几乎必遇一次。3.3 官方教程没讲的 app 划分逻辑真实项目里一个常见问题是一个models.py里堆了太多模型。官方教程只有一个Question和Choice看不出问题。但当你做一个博客系统时如果用户、文章、评论、标签、友链全塞在一个 app 里代码会迅速失控。推荐思路是按业务边界切分user_app用户扩展信息、登录注册相关逻辑blog_app文章、分类、标签comment_app评论、点赞每个 app 有自己的models.py、views.py、urls.py应用之间通过外键或明确接口关联。你要知道 Django 的 app 不是微服务项目内部它们共享同一个数据库但代码边界清晰能让你后期维护时少掉头发。官方教程里没有讲这套组织方法论但这恰恰是实战结果里最有价值的部分。4. 查询与删除对象ORM 实操里那些教程没强调的细节4.1 懒加载为什么查完数据库没被执行官方教程里写了Question.objects.all()和filter()但没有明确告诉你 QuerySet 是惰性的。简单说Question.objects.filter(pub_date__year2024)这一行不会立刻打 SQL只有当你真正“使用”这个结果时遍历它、取长度、判断是否存在Django 才去数据库查询。这意味着两件事。第一你可以链式叠加过滤条件最后只执行一次查询qs Question.objects.filter(pub_date__year2024) qs qs.filter(question_text__contains投票) qs qs.order_by(-pub_date)第二如果你不小心把 QuerySet 存起来在模板或视图里多次使用它每次使用都可能触发新查询。比如在if判断里用一次在 for 循环里又用一次底层就是两次 SQL。小项目没问题数据量大了以后这就是性能隐患。解决办法是及时list()转成列表或者在循环外先取一次。4.2 删除对象delete() 到底删了什么官方教程的投票应用没有删除功能所以很多新手对删除只有model.objects.get(id1).delete()这一步的理解。这个理解太浅了。delete()会真正从数据库里删掉这一行数据。如果你是ForeignKey的“一”方被删后与之关联的“多”方会根据on_delete参数行动。官方教程的Question和Choice之间用的就是级联删除models.CASCADE删掉问题选项会被一起带走。但在真实项目里直接物理删除很多时候不是好选择。比如用户注销账号你真的希望把用户的所有评论、订单历史全删干净吗正常做法是软删除给模型加一个is_deleted字段或者deleted_at时间字段删除时只更新这个标记查询时默认过滤掉已标记的。这样数据还在需要审计时能查到想恢复也容易。我这里给你一个软删除常用的设计思路class Article(models.Model): title models.CharField(max_length200) content models.TextField() is_deleted models.BooleanField(defaultFalse) deleted_at models.DateTimeField(nullTrue, blankTrue)查询时这样过滤Article.objects.filter(is_deletedFalse)再用自定义管理器把这条规则固化class ArticleManager(models.Manager): def get_queryset(self): return super().get_queryset().filter(is_deletedFalse)之后所有业务代码里写Article.objects.all()就自动排除已删除数据。这是我从实际项目里体会最深的一个模式ORM 的默认查询入口就是软删除过滤层比你在每个视图里手动加filter(is_deletedFalse)可靠得多。4.3 实战里最有用的几个 QuerySet 技巧values()和values_list()是官方教程没教但实战高频使用的。当你只需要模型里的几个字段不想加载整个对象时用values()返回字典列表values_list()返回元组列表。这样省内存、省时间适合导出报表或 AJAX 接口。Question.objects.values(id, question_text) # 输出: [{id: 1, question_text: 今天吃什么}, ...]select_related和prefetch_related是用来处理关联对象查询性能的。简单来说select_related适合“一对一”和“外键”这种单条关联一次 JOIN 查出来prefetch_related适合“多对多”和“反向外键”先查主表再批量查关联表。官方教程里看不到这两者的必要因为数据少等你页面一卡通常就是 N1 查询在作怪。F 表达式我也提一下。它用于在查询中引用字段值本身不查出来再赋值直接由数据库完成运算。比如给阅读量加一from django.db.models import F Article.objects.filter(id1).update(read_countF(read_count) 1)这个路径不会出现并发时先读后写导致计数丢失的问题。5. 登录认证与 Cookie Token 设置给投票应用补上用户体系5.1 官方教程留的坑登录只做了一半官方教程的投票应用没有用户注册和登录只有一个 Admin 后台的登录。Admin 登录是 Django 内置的开箱即用。但真实项目需要用户在站前端登录、注册并且后续请求能识别“你是谁”。Django 内置的django.contrib.auth包含完整的认证框架用户模型、会话、权限。官方教程没讲透的是它如何在 HTTP 无状态请求里维持登录状态——靠的是 Session默认存在数据库的django_session表中浏览器记住的是 sessionid 这个 Cookie。方案一保持使用服务端 Session。对于小型项目这是最省事的安全性也有保证。你在视图里写request.user.is_authenticated就能判断是否登录。方案二前端需要频繁访问这些接口但不想每次都带 CSRF token、不想依赖浏览器 Cookie 同源策略时就要考虑 token 认证。这个方法在前后端分离项目里用得最多。5.2 用 Cookie 设置 token 的完整做法这里用一个实战思路用户登录成功后我生成一个 token 写入数据库或缓存同时通过response.set_cookie()把它写到浏览器。为什么要用 Cookie 而不是让前端把 token 存到 localStorage因为 localStorage 的 token 很容易被第三方脚本通过 XSS 窃取Cookie 设置了HttpOnly后JavaScript 读不到它的内容能有效降低 XSS 风险。简单实现如下import uuid from django.http import JsonResponse from django.contrib.auth import authenticate def login_view(request): if request.method POST: username request.POST.get(username) password request.POST.get(password) user authenticate(request, usernameusername, passwordpassword) if user is not None: token uuid.uuid4().hex # 存到缓存有效期 7 天 cache.set(fauth_token:{token}, user.id, timeout7 * 24 * 3600) response JsonResponse({code: 0, msg: ok}) response.set_cookie( auth_token, token, httponlyTrue, samesiteLax, max_age7 * 24 * 3600, secureFalse, # 生产环境记得改为 True走 HTTPS path/, ) return response return JsonResponse({code: 1, msg: 用户名或密码错误})取用户时写一个简单的认证后端或者直接在视图中解析 Cookiefrom django.core.cache import cache from django.contrib.auth.models import User def get_login_user(request): token request.COOKIES.get(auth_token) if not token: return None user_id cache.get(fauth_token:{token}) if not user_id: return None return User.objects.filter(iduser_id).first()这段代码我已经在多个项目里用过足够简单也够用。如果要更标准可以把这部分包成基于AuthenticationMiddleware的认证后端但核心逻辑就是上面这些。5.3 CSRF 和 CORS两个新手容易混的问题官方教程里的表单都要写{% csrf_token %}这是 Django 的 CSRF 防护。但如果你用第三方 API 工具Postman、Apifox测试 POST 接口经常会报 CSRF 验证失败。开发阶段可以先豁免生产环境建议保留。当你做前后端分离时登录接口从另一个域名或端口发出请求时就会有跨域问题这由 CORS 配置管辖。简单说同源请求靠 Cookie跨域请求需要在响应头中告诉浏览器允许哪些域名访问。Django 没有内置 CORS 处理通常装django-cors-headers。配置如下INSTALLED_APPS [ ... corsheaders, ] MIDDLEWARE [ corsheaders.middleware.CorsMiddleware, ... ] CORS_ALLOWED_ORIGINS [ http://localhost:3000, ]我见过很多人把 CSRF 和 CORS 搞混CSRF 防的是伪造请求CORS 管的是浏览器同源策略导致的跨域权限。互相之间有联系但不是一个东西。排查问题时先分清你遇到的到底是谁。6. 用 WebSocket 实现后台数据推送让页面不再等人刷新6.1 为什么需要 WebSocket轮询到底差在哪传统 HTTP 请求是请求-响应模型前端发起请求后端返回结果。如果后台数据变化了想推给前端通常只能让前端隔几秒轮询一次接口。这种方案在小规模场景能用但有几方面局限性实时性差几秒延迟、浪费资源大部分轮询请求都是空回来的、服务端压力大频繁建连、频繁查询。WebSocket 解决的是全双工通信的问题前端和服务器建立起一条长连接后服务器可以随时主动推送消息给前端前端也可以随时发消息给服务器。适合实时通知、在线状态、数据看板、聊天消息这类场景。Django 原生不支持 WebSocket因为它走的是 HTTP 的 WSGI 协议。要支持 WebSocket得切换到异步——这就是 Django Channels 的用途。Channels 基于 ASGI可以同时处理 HTTP 和 WebSocket。6.2 用 Django Channels 实现后台推送这里我以一个“后台数据变化后前端实时收到通知”的场景为例。第一步安装 Channelspip install channels第二步把项目从 WSGI 模式转换成 ASGI 模式。找到asgi.py文件改成这样import os from django.core.asgi import get_asgi_application from channels.routing import ProtocolTypeRouter, URLRouter from django.urls import path from your_app.consumers import NotificationConsumer os.environ.setdefault(DJANGO_SETTINGS_MODULE, myproject.settings) application ProtocolTypeRouter({ http: get_asgi_application(), websocket: URLRouter([ path(ws/notifications/, NotificationConsumer.as_asgi()), ]), })第三步编写消费者。消费者相当于 WebSocket 的视图负责处理连接建立、收到消息、断开连接from channels.generic.websocket import AsyncJsonWebsocketConsumer class NotificationConsumer(AsyncJsonWebsocketConsumer): async def connect(self): await self.accept() # 可以把连接分组方便后台定向推送 await self.channel_layer.group_add(notifications, self.channel_name) async def disconnect(self, close_code): await self.channel_layer.group_discard(notifications, self.channel_name) async def notify(self, event): # 后台调用 group_send 时会触发这个方法 await self.send_json({ message: event[message], })第四步在后台任意位置推送消息from channels.layers import get_channel_layer from asgiref.sync import async_to_sync channel_layer get_channel_layer() def push_notification(message): async_to_sync(channel_layer.group_send)( notifications, { type: notify, message: message, } )这样只要调用push_notification(有新订单)前端就能实时收到消息。6.3 前端接入与踩坑实录前端用原生 JavaScript 接入很简单const socket new WebSocket(ws://localhost:8000/ws/notifications/); socket.onmessage function(event) { const data JSON.parse(event.data); console.log(收到推送, data.message); };但我实际使用中踩过几个坑值得记下来。第一个坑是通道层配置。生产环境 Channels 需要 Redis 作为通道层开发环境可以只用 InMemory 通道层CHANNEL_LAYERS { default: { BACKEND: channels.layers.InMemoryChannelLayer, }, }但 InMemory 只在单进程、单 worker 下有效。一旦你用多个 worker推送消息很可能发不到你连接所在的那个进程。生产环境务必换 Redis我最早上线时忘了换结果推送消息时好时坏排查了大半天。第二个坑是async_to_sync。普通 Django 视图是同步的调用 Channels 的异步方法要包一层async_to_sync。很多人第一次写的时候漏掉这个会报SynchronousOnlyOperation错误。第三个坑是部署时的 ASGI 服务器选择。开发阶段用uvicorn或者 Daphne 都可以生产环境也需要对应配置反向代理支持 WebSocket 升级。Nginx 层需要设置Upgrade头这个在常规 HTTP 配置里不会自带忘了配置的话客户端永远连不上 wss。第四个坑是连接鉴权。WebSocket 连接建立时如何知道用户身份我常在connect()中通过查询字符串或 Cookie 拿到 token再解析用户。需要注意 WebSocket 的握手阶段没有普通视图的request但 Channels 提供了一个scope对象里面带着 Cookie 等 HTTP 会话信息。简单示例如下from django.contrib.auth.models import AnonymousUser async def connect(self): cookies self.scope.get(cookies, {}) token cookies.get(auth_token) # 解析 token找到 user存到 self.scope[user] 中 self.scope[user] await get_user_by_token(token)7. 常见问题与排查技巧实战中踩过的那些坑7.1 新手必踩的五个坑官方教程之后的独立开发最容易踩的坑我列一下都是真实项目中多次见到的。第一个是静态文件 404。本地开发时DEBUGTrue的情况下静态文件通常没问题但部署后DEBUGFalse时Django 不再帮你处理静态文件需要collectstatic收集到指定目录并交给 Web 服务器托管。很多人部署后页面样式全丢就是漏了这一步。第二个是数据库迁移冲突。多人协作时经常出现你本地改了模型同事也改了同一个模型两边各自生成迁移文件合并时就会有冲突。不要怕Django 有内置合并命令python manage.py makemigrations --merge第三种是时区问题。USE_TZ True时Django 存储和处理的都是带时区的时间如果你在前端直接用datetime.now()跟模型里的时间比较容易差 8 小时。统一使用django.utils.timezone.now()。第四种是query.get()的异常处理。get()匹配不到数据会抛DoesNotExist匹配到多条会抛MultipleObjectsReturned。如果你不确定数据唯一性最好用 try-except 包住或者用filter().first()。第五种是表单验证的坑。官方教程里的form.is_valid()看起来简单但实际项目里你往往需要自定义验证逻辑。一个常见误区是在clean()里直接改self.cleaned_data但忘了cleaned_data可能还没有字段值。正确做法是逐个字段定义clean_字段名()方法。7.2 排查问题的一个固定顺序我调 Django 问题一般遵循这个顺序看浏览器 Network 面板确认请求 URL、状态码、响应体。很多时候问题不在后端而是前端没发对请求。看后端日志。Django 开发服务器的终端输出会打印 SQL 和异常堆栈这是定位问题的宝藏。如果异常信息不明用python manage.py shell复现。可以手动执行模型查询和函数调用比在视图里盲目打日志快得多。模型、视图逻辑都没问题时再怀疑配置。检查settings.py里的INSTALLED_APPS、中间件顺序、URL 路由。这套顺序帮我排掉过六成以上的问题。真正复杂的往往不是技术而是数据问题——比如旧数据的脏数据导致新逻辑报错这种只能靠写脚本清洗。7.3 调试技巧少走冷门弯路print()大法虽然不高级但配合python manage.py shell真的很实用。我经常把要验证的代码片段直接粘进 shell 里跑省去了反复重启开发服务器的时间。另外一个冷门技巧是django-debug-toolbar。它会在页面侧边显示 SQL 查询数量、耗时、模板加载情况对性能优化很有帮助。装上之后你会发现一个页面居然查了几十次数据库——这就是 N1 问题的证据然后用select_related和prefetch_related修复。关于日志建议早点用标准库的logging而不是print。配置一个文件日志处理器把异常写入 logs 文件对排查线上问题是长期投资。Django 有个内置的django.request日志器配置好以后 5xx 错误会自动记录请求路径和异常信息。8. 扩展方向与我的个人体会官方教程只是一个开始这句话很多人说但实践之后才能体会到它的分量。拍卖完投票应用之后如果你想继续深入我建议按这样的顺序来先做一个带用户注册登录的简单内容发布系统把用户体系、session、表单验证、soft delete 都用进去然后做接口化改造试着用 JsonResponse 返回数据接入 token 认证最后再碰 WebSocket 和异步任务做实时通知或者后台一键推送。我个人的实际体会是Django 的坑多数不在框架本身而在那些你没理解透的概念上——懒惰查询、时区、CSRF、CORS、ASGI 和 WSGI 的区别。每一个概念初看都很简单但组合起来之后问题会变得诡异。这篇记录里很多内容也是我自己踩坑之后才想明白的。希望你看完能少走一些弯路。最后分享一个小技巧官方教程的投票应用项目不要删把它当成一个实验场。你学到的新东西比如 token 登录、WebSocket、类视图都可以先在这个小项目里试一遍。小项目不会因为搞挂而有负担但你能完整地跑通整个链路这个经验积累对下一个正式项目非常宝贵。如果你是刚把官方教程做完先别急着找更复杂的教程。把投票应用从“能跑”改到“像样”加上用户注册、让用户可以投票后看到结果、给后台加上一些筛选功能。这个改造过程比看十个新教程都更有价值。