这次我们直接看 Django。很多新手学 Python Web 开发第一脚踩进去的就是 Django但大多数人卡住不是因为代码难而是不知道整条学习路线到底该怎么走。今天这篇不堆概念只抓一条主线一个请求从浏览器发出到 Django 返回响应中间到底经过哪些环节。把这根线捋顺后面学模型、学模板、学 Admin 后台都是顺理成章的事。Django 是 Python 生态里最成熟的全栈 Web 框架之一自带 ORM、Admin 后台、认证系统、表单处理、模板引擎适合做内容管理系统、数据管理后台、API 服务、内部工具平台这类项目。它不像 Flask 那样需要自己拼装各种扩展而是“全家桶”式的设计你按照它规定的目录结构和约定去写代码项目天然具备清晰的模块边界。这篇文章会带你完成搭建本地开发环境、创建 Django 项目和 App、理解 MVT 架构、写一个能处理请求的视图、用 ORM 操作数据库、注册 Admin 后台、最后给出一套新手最容易踩坑的排查清单。全程跟着敲一遍你就能掌握 Django 的核心主线而不是东看一个概念、西看一段代码。1. 核心能力速览先把 Django 能做什么、门槛在哪说清楚。下面这张表是给新手的第一份“项目说明书”能力项说明框架类型Python 全栈 Web 框架自带 ORM、Admin、模板、认证核心架构MVTModel-View-Template请求入口是 URLconf适合场景内容管理、后台系统、数据平台、API 服务、企业级 Web 应用开发语言Python 3.x推荐使用虚拟环境隔离依赖数据库支持默认 SQLite可切换 MySQL、PostgreSQL、Oracle 等启动方式python manage.py runserver自带开发服务器是否支持批量任务可通过 Django Command 或 Celery 实现是否支持 API搭配 Django REST Framework 快速构建 RESTful API新手门槛需要掌握 Python 基础、命令行基础、HTTP 基本概念国内使用情况广泛适合快速交付业务系统学习资源多这张表不需要全记住。你只需要知道Django 给你搭好了一套完整的 Web 应用骨架你要做的是往里面填业务逻辑。2. 明确主线为什么必须先搞懂“请求处理流程”新手学 Django 最容易犯的错是今天看一个模型教程明天看一个模板教程后天又去折腾 Admin结果每个知识点都看过但让你独立写一个页面却无从下手。问题不在知识点本身而在于没有建立执行顺序的概念。Django 应用的本质是一次 HTTP 请求的处理过程用户在浏览器输入 URL点击链接或提交表单。请求到达 Django 服务器。Django 根据urls.py里的路由配置找到对应的视图函数或视图类。视图函数执行业务逻辑可能需要操作数据库。视图把处理结果交给模板渲染。服务器把渲染后的 HTML 返回给浏览器。这就是主线。所有 Django 知识点都可以挂在这条主线上模型Model解决的是第 4 步里“操作数据库”的问题。视图View解决的是第 3、4 步里“处理请求和业务逻辑”的问题。模板Template解决的是第 5 步里“如何展示数据”的问题。URL 配置解决的是第 3 步里“如何找到视图”的问题。Admin 后台则是 Django 直接帮你生成的一套“可视化的模型管理界面”。你不需要同时学完所有细节。先走通这条主线哪怕只是做一个最简单的“返回当前时间”的页面你对 Django 的认知就会从“看懂了”变成“会用了”。3. 环境准备与前置条件在写代码之前先把环境准备好。下面是一套通用的检查清单适用于大多数 Django 开发场景。3.1 需要安装的软件软件用途说明Python 3.x运行 Django推荐 3.9 及以上版本新版 Django 已不支持旧版 Pythonpip安装 Python 包Python 安装时自带virtualenv 或 venv创建虚拟环境隔离不同项目的依赖避免版本冲突代码编辑器编辑代码推荐 VS Code 或 PyCharm新手用 VS Code 轻量一些Git版本管理可选但强烈建议养成习惯3.2 检查 Python 是否安装成功打开命令行工具Windows 上是 CMD 或 PowerShellmacOS 和 Linux 上是终端输入python --version如果提示找不到命令尝试python3 --version看到类似Python 3.12.x的输出说明 Python 已经安装成功。3.3 创建虚拟环境并安装 Django虚拟环境是新手最应该先养成的习惯。它保证你下载的 Django 版本不会污染系统全局 Python也不会和其他项目冲突# 创建虚拟环境目录名用 venv也可以叫 .venv python -m venv venv # 激活虚拟环境 # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate激活成功后命令行前面会出现(venv)标记。然后在虚拟环境里安装 Djangopip install django安装完成后检查版本python -m django --version能看到版本号说明 Django 安装成功。3.4 开发环境配置建议编辑器开启Python扩展和Django模板语法高亮扩展。如果使用 VS Code可以在项目根目录创建.vscode/settings.json把 Python 解释器指向虚拟环境路径。使用 PyCharm 的话创建项目时直接选择虚拟环境即可图形化操作对新手更友好。环境准备到这里就够了。不需要提前配数据库Django 默认使用 SQLite零配置直接可用。4. 创建 Django 项目与应用这是新手第一次接触 Django 目录结构的关键步骤。记住一个核心概念项目Project是一个网站的整体配置应用App是网站里一个具体的功能模块。一个项目可以包含多个应用。4.1 创建项目进入你打算存放代码的目录执行django-admin startproject myblog这里的myblog是项目名。执行后会生成如下结构myblog/ manage.py myblog/ __init__.py settings.py urls.py asgi.py wsgi.py重点说明manage.py项目的命令行管理工具启动服务器、执行数据库迁移都靠它。settings.py全局配置文件包括数据库、应用注册、静态文件路径等。urls.py全局 URL 路由入口所有请求都会先经过这里。asgi.py和wsgi.py部署时使用的服务器入口开发阶段不用管。4.2 创建应用进入项目目录cd myblog python manage.py startapp blogblog就是这个项目里的一个应用。生成结果blog/ __init__.py admin.py apps.py models.py tests.py views.py migrations/ __init__.py新手阶段重点关注三个文件models.py定义数据库表结构。views.py写业务逻辑处理 HTTP 请求。admin.py注册模型到 Admin 后台。4.3 将应用注册到项目打开myblog/settings.py在INSTALLED_APPS列表中添加blogINSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, blog, # 新增这一行 ]这一步不做后面创建的模型和 Admin 页面不会生效。4.4 启动开发服务器验证回到项目根目录执行python manage.py runserver看到类似下面的输出说明项目已经跑起来了Starting development server at http://127.0.0.1:8000/浏览器访问http://127.0.0.1:8000/如果出现 Django 默认的“Congratulations”页面说明环境完全正常。此时你就已经走通了 Django 主线中的第一步项目能启动Django 能接收 HTTP 请求。5. 功能测试与效果验证从 URL 到视图环境跑通之后接下来要做的第一件正经事是让 Django 返回一个由我们自己写的页面。5.1 编写第一个视图函数打开blog/views.py写入from django.http import HttpResponse def index(request): return HttpResponse(你好Django这是我的第一个页面。)这里先不涉及模板和数据库只返回最简单的文本。目的是验证 URL 配置和视图函数的调用链路是否通畅。5.2 配置 URL 路由Django 的请求处理第一站是项目的urls.py。打开myblog/urls.py把请求分发到blog应用from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(blog.urls)), ]然后在blog应用目录下新建urls.py文件内容如下from django.urls import path from . import views urlpatterns [ path(, views.index, nameindex), ]这里path(, ...)表示访问根路径/时交给views.index处理。5.3 重启并验证如果runserver还开着保存代码后它会自动重载。在浏览器刷新http://127.0.0.1:8000/。预期结果页面显示“你好Django这是我的第一个页面。”5.4 判断是否成功的标准检查项预期结果页面是否显示自定义文本是终端是否有报错无修改views.py后刷新页面是否立即生效是这一步走通说明你已经理解了 Django 主线的关键一环URL - View。5.5 常见失败原因问题现象可能原因排查方式页面 404urls.py配置错误检查myblog/urls.py和blog/urls.py的路径参数页面 500视图函数有语法错误查看终端错误堆栈修改代码后没反应开发服务器未自动重载手动重启runserver6. 模型与 ORM让数据可以持久化Web 应用不会只返回固定文本。真实业务的核心是数据用户提交的内容要存下来页面展示的内容要从数据库读出来。这一节解决的就是“主线第 4 步操作数据库”。6.1 定义模型打开blog/models.py定义一个简单的文章模型from django.db import models class Article(models.Model): title models.CharField(max_length100, verbose_name标题) content models.TextField(verbose_name内容) created_at models.DateTimeField(auto_now_addTrue, verbose_name创建时间) def __str__(self): return self.title class Meta: verbose_name 文章 verbose_name_plural verbose_name每一行代码含义如下CharField短文本字段必须指定max_length。TextField长文本字段。DateTimeField(auto_now_addTrue)创建时自动记录当前时间。__str__Admin 后台和命令行中显示对象的名称。6.2 生成数据库迁移文件并执行迁移Django 用“迁移”机制把模型同步到数据库。执行两条命令python manage.py makemigrations python manage.py migratemakemigrations根据模型变化生成迁移文件存放在blog/migrations/。migrate把迁移文件真正执行到数据库。执行完成后Django 会自动创建数据表。使用默认 SQLite 时不需要任何额外配置数据库文件db.sqlite3会自动生成在项目根目录。6.3 用 ORM 增删改查Django 不要求你写 SQL。在 Python 命令行里执行以下操作即可完整验证 ORM 能力python manage.py shell这是一个交互式 Python 环境导入了 Django 的配置。依次输入# 新增一条数据 from blog.models import Article article Article(titleDjango 新手教程, content这是第一篇文章) article.save() # 查询所有数据 Article.objects.all() # 查询单条数据 a Article.objects.get(id1) # 修改数据 a.title Django 新手教程已修改 a.save() # 执行查询并过滤 Article.objects.filter(title__containsDjango) # 删除对象 a.delete()注意get(id1)只能返回一条记录如果多条记录匹配会报MultipleObjectsReturned没有匹配则报DoesNotExist。如果只是判断是否存在推荐使用.filter().exists()。用exit()退出 shell。6.4 判断 ORM 是否掌握你不需要背 API。只需要理解三个概念模型类等于数据库表类的属性对应表的字段。objects是模型管理器所有查询入口都从它开始。save()和delete()是写操作核心新增、修改都要先拿到对象再调用save()删除调用delete()。ORM 这条线走通你就能完成大部分日常数据操作。7. 模板与静态文件让页面真正可用数据已经能从数据库读写但用户看到的还是视图函数返回的纯文本。这一节走完主线第 5 步View - Template。7.1 创建模板目录在blog应用目录下新建templates/blog/目录。Django 会自动从每个应用的templates目录下寻找模板文件。新建blog/templates/blog/article_list.html!DOCTYPE html html langzh head meta charsetUTF-8 title文章列表/title /head body h1Django 文章列表/h1 ul {% for article in articles %} li{{ article.title }} - {{ article.created_at }}/li {% empty %} li暂无文章/li {% endfor %} /ul /body /html7.2 修改视图函数返回模板在blog/views.py中新增一个使用模板的视图from django.shortcuts import render from .models import Article def article_list(request): articles Article.objects.all().order_by(-created_at) return render(request, blog/article_list.html, {articles: articles})修改blog/urls.py新增路由urlpatterns [ path(, views.index, nameindex), path(articles/, views.article_list, namearticle_list), ]7.3 验证模板渲染浏览器访问http://127.0.0.1:8000/articles/。如果之前用 ORM 添加过数据页面会显示文章标题和创建时间。如果没数据会显示“暂无文章”。到这里你可以先回http://127.0.0.1:8000/的根路径。此时再把views.index改成调用article_list视图让首页直接展示文章列表from django.shortcuts import render from .models import Article def index(request): articles Article.objects.all().order_by(-created_at) return render(request, blog/article_list.html, {articles: articles})刷新首页你会发现主线全部串起来了浏览器请求根路径/。myblog/urls.py把请求分发给blog/urls.py。blog/urls.py匹配到views.index。index视图从数据库读取文章列表。模板渲染数据。Django 返回完整 HTML 页面。这就是整个 Django 的核心主线。7.4 静态文件配置开发阶段默认的静态文件配置已经写好不需要额外修改。在blog/templates/blog/下再建一个static/blog/目录放入style.css然后在模板顶部加载{% load static %} !DOCTYPE html html langzh head meta charsetUTF-8 title文章列表/title link relstylesheet href{% static blog/style.css %} /head具体样式可以自行编写。只需要知道模板中要用{% static %}标签引用静态文件Django 会自动拼接静态文件路径。8. Admin 后台零代码生成管理界面Django 的 Admin 后台是它最吸引新手的特性之一。你只需要写几行代码就能得到一个支持增删改查的完整管理界面。8.1 创建超级用户在命令行执行python manage.py createsuperuser按提示输入用户名、邮箱、密码。密码至少 8 位不要设置太简单。8.2 注册模型到 Admin打开blog/admin.pyfrom django.contrib import admin from .models import Article admin.register(Article) class ArticleAdmin(admin.ModelAdmin): list_display [id, title, created_at] search_fields [title]list_display指定列表页显示的字段search_fields开启搜索框。8.3 访问后台并验证启动服务器后浏览器访问http://127.0.0.1:8000/admin/输入超级用户账号登录。预期效果页面显示“文章”模块。可以点击“增加”新建文章。可以编辑、删除文章。列表页显示标题和创建时间右上角有搜索框。这一步完成你的第一个 Django 项目已经具备“写文章 - 存数据库 - 页面展示 - 后台管理”的完整闭环。8.4 注意 Admin 的边界Admin 后台适合内部管理、运营编辑、数据维护不适合直接给普通用户当前台使用。它的设计目标是给管理员用的工具界面不是面向终端用户的产品界面。如果要给用户使用需要自定义视图和模板或者使用 Django REST Framework 开发 API 接口。9. 接口 API 与批量任务扩展如果你需要把 Django 的能力开放给其他系统或者做前后台分离最常用的方案是 Django REST FrameworkDRF。9.1 安装 DRF在虚拟环境中安装pip install djangorestframework在settings.py的INSTALLED_APPS中添加rest_framework,9.2 创建序列化器在blog应用下新建serializers.pyfrom rest_framework import serializers from .models import Article class ArticleSerializer(serializers.ModelSerializer): class Meta: model Article fields [id, title, content, created_at]9.3 创建 API 视图在blog/views.py中添加from rest_framework.decorators import api_view from rest_framework.response import Response from .serializers import ArticleSerializer api_view([GET, POST]) def article_api(request): if request.method GET: articles Article.objects.all() serializer ArticleSerializer(articles, manyTrue) return Response(serializer.data) elif request.method POST: serializer ArticleSerializer(datarequest.data) if serializer.is_valid(): serializer.save() return Response(serializer.data, status201) return Response(serializer.errors, status400)在blog/urls.py添加路由path(api/articles/, views.article_api, namearticle_api),9.4 测试 API启动服务后访问http://127.0.0.1:8000/api/articles/浏览器会显示 JSON 数据。也可以使用命令行测试curl http://127.0.0.1:8000/api/articles/用 POST 新增一篇curl -X POST http://127.0.0.1:8000/api/articles/ \ -H Content-Type: application/json \ -d {title: API 示例, content: 通过接口创建}9.5 批量任务建议Django 里做批量任务有两种推荐方式简单场景写 Django Command用python manage.py my_command执行适合定时脚本、数据清洗、邮件发送。复杂场景接入 Celery Redis适合异步任务、长耗时任务、需要重试机制的任务队列。新手阶段优先用 Django Command 解决问题它零依赖、易调试。等任务量大了再考虑 Celery。10. 常见问题与排查方法以下是新手使用 Django 时最常遇到的问题建议直接收藏作为排查手册问题现象可能原因排查方式解决方案pip install django报错网络问题或 Python 版本过低查看错误信息最后几行换国内 pip 源后重试django-admin不是内部或外部命令虚拟环境未激活命令行提示符前是否有(venv)执行虚拟环境激活命令页面 404URL 路由不匹配检查urls.py中的路径参数对比浏览器地址和path参数页面 500视图或模型代码报错查看终端完整报错堆栈根据堆栈定位到具体文件和行号数据库操作报no such table忘记执行migrate查看blog/migrations目录执行python manage.py migrateAdmin 后台登录后是英文本地化配置未打开打开settings.py设置LANGUAGE_CODE zh-hans修改models.py后查不到新字段未生成迁移文件查看迁移目录执行makemigrations后再migrate端口被占用其他程序已使用 8000 端口查看终端报错信息更换端口python manage.py runserver 8001模板变量不显示变量名或上下文键名不一致对比视图传入的字典键和模板中的变量名确保两者完全一致API 返回 403Django 的 CSRF 校验检查请求方式和 Django 配置开发阶段可在视图上加csrf_exempt但不推荐在生产使用migrate后项目启动变慢数据库连接或迁移历史过多观察启动日志正常现象首次迁移后启动速度会恢复另外两个常见场景依赖安装失败建议全程使用虚拟环境并且使用 Python 3.9 以上版本避免版本兼容性问题。显存或资源占用问题Django 本身是 Web 框架不涉及 GPU 推理资源占用以内存为主。开发服务器是单线程的只用于本地开发不要直接用于生产环境。11. 最佳实践与使用建议学 Django 的正确姿势不是把所有文档读完而是尽快完成一个最小闭环。建议按这个顺序推进第一个项目不要复杂。做一个“个人名片页 留言板”就够了前端页面展示个人信息留言板存数据库Admin 后台管理留言。这个项目包含 Django 的完整主线又不会让你陷入复杂的业务逻辑。代码组织上坚持一条原则业务逻辑写进视图或独立的 service 层不要在模板里写复杂逻辑。模板只负责展示查询逻辑放视图层数据处理放模型方法或独立工具模块。虚拟环境一定要用。一个项目对应一个虚拟环境后期部署到服务器时用pip freeze requirements.txt导出依赖在服务器上执行pip install -r requirements.txt就能复现环境。数据库切换要趁早。SQLite 虽然零配置但生产环境部署建议换用 PostgreSQL 或 MySQL。切换时只需修改settings.py中的数据库配置ORM 代码不用改这也正是 Django 的优势。文件目录提前规划。建议按照业务的自然边界拆分应用例如用户相关一个 App、文章相关一个 App。不要把所有模型塞进同一个 App否则项目变大后非常难维护。安全方面要注意开发环境把DEBUG True打开方便排查问题部署到生产环境必须把DEBUG设为False同时修改ALLOWED_HOSTS否则会出现安全提示。涉及用户上传文件、权限管理、支付回调等场景一定要先看 Django 官方安全文档。12. 下一步能做什么主线走通之后你的能力边界已经打开。下一步可以根据自己的方向选择想做标准业务后台学习分页、表单验证、消息通知、用户权限管理。想做前后端分离深入学习 Django REST Framework把重点放在序列化器、认证权限、视图集和路由上。想部署上线学习 Gunicorn Nginx 的部署方案配置静态文件收集使用 PostgreSQL 替换 SQLite。想处理异步任务把 Celery 接进来用 Redis 做消息队列。想学其它 Python Web 框架可以对比学习 Flask 或 FastAPI那时你会发现 Django 的“全家桶”设计思路和微框架是完全不同的两种风格。最后给一个很实际的小建议给自己留一个“最小可运行项目”目录里面保存环境创建命令、项目初始化命令、核心示例代码。当你学新知识点时在这个最小项目上做实验比每次新建项目快得多也比看文档印象深。第一次完整跑通 Django 之后后面每一个新功能都只是往这个骨架上加肌肉而已。
这次我们直接看 Django。很多新手学 Python Web 开发第一脚踩进去的就是 Django但大多数人卡住不是因为代码难而是不知道整条学习路线到底该怎么走。今天这篇不堆概念只抓一条主线一个请求从浏览器发出到 Django 返回响应中间到底经过哪些环节。把这根线捋顺后面学模型、学模板、学 Admin 后台都是顺理成章的事。Django 是 Python 生态里最成熟的全栈 Web 框架之一自带 ORM、Admin 后台、认证系统、表单处理、模板引擎适合做内容管理系统、数据管理后台、API 服务、内部工具平台这类项目。它不像 Flask 那样需要自己拼装各种扩展而是“全家桶”式的设计你按照它规定的目录结构和约定去写代码项目天然具备清晰的模块边界。这篇文章会带你完成搭建本地开发环境、创建 Django 项目和 App、理解 MVT 架构、写一个能处理请求的视图、用 ORM 操作数据库、注册 Admin 后台、最后给出一套新手最容易踩坑的排查清单。全程跟着敲一遍你就能掌握 Django 的核心主线而不是东看一个概念、西看一段代码。1. 核心能力速览先把 Django 能做什么、门槛在哪说清楚。下面这张表是给新手的第一份“项目说明书”能力项说明框架类型Python 全栈 Web 框架自带 ORM、Admin、模板、认证核心架构MVTModel-View-Template请求入口是 URLconf适合场景内容管理、后台系统、数据平台、API 服务、企业级 Web 应用开发语言Python 3.x推荐使用虚拟环境隔离依赖数据库支持默认 SQLite可切换 MySQL、PostgreSQL、Oracle 等启动方式python manage.py runserver自带开发服务器是否支持批量任务可通过 Django Command 或 Celery 实现是否支持 API搭配 Django REST Framework 快速构建 RESTful API新手门槛需要掌握 Python 基础、命令行基础、HTTP 基本概念国内使用情况广泛适合快速交付业务系统学习资源多这张表不需要全记住。你只需要知道Django 给你搭好了一套完整的 Web 应用骨架你要做的是往里面填业务逻辑。2. 明确主线为什么必须先搞懂“请求处理流程”新手学 Django 最容易犯的错是今天看一个模型教程明天看一个模板教程后天又去折腾 Admin结果每个知识点都看过但让你独立写一个页面却无从下手。问题不在知识点本身而在于没有建立执行顺序的概念。Django 应用的本质是一次 HTTP 请求的处理过程用户在浏览器输入 URL点击链接或提交表单。请求到达 Django 服务器。Django 根据urls.py里的路由配置找到对应的视图函数或视图类。视图函数执行业务逻辑可能需要操作数据库。视图把处理结果交给模板渲染。服务器把渲染后的 HTML 返回给浏览器。这就是主线。所有 Django 知识点都可以挂在这条主线上模型Model解决的是第 4 步里“操作数据库”的问题。视图View解决的是第 3、4 步里“处理请求和业务逻辑”的问题。模板Template解决的是第 5 步里“如何展示数据”的问题。URL 配置解决的是第 3 步里“如何找到视图”的问题。Admin 后台则是 Django 直接帮你生成的一套“可视化的模型管理界面”。你不需要同时学完所有细节。先走通这条主线哪怕只是做一个最简单的“返回当前时间”的页面你对 Django 的认知就会从“看懂了”变成“会用了”。3. 环境准备与前置条件在写代码之前先把环境准备好。下面是一套通用的检查清单适用于大多数 Django 开发场景。3.1 需要安装的软件软件用途说明Python 3.x运行 Django推荐 3.9 及以上版本新版 Django 已不支持旧版 Pythonpip安装 Python 包Python 安装时自带virtualenv 或 venv创建虚拟环境隔离不同项目的依赖避免版本冲突代码编辑器编辑代码推荐 VS Code 或 PyCharm新手用 VS Code 轻量一些Git版本管理可选但强烈建议养成习惯3.2 检查 Python 是否安装成功打开命令行工具Windows 上是 CMD 或 PowerShellmacOS 和 Linux 上是终端输入python --version如果提示找不到命令尝试python3 --version看到类似Python 3.12.x的输出说明 Python 已经安装成功。3.3 创建虚拟环境并安装 Django虚拟环境是新手最应该先养成的习惯。它保证你下载的 Django 版本不会污染系统全局 Python也不会和其他项目冲突# 创建虚拟环境目录名用 venv也可以叫 .venv python -m venv venv # 激活虚拟环境 # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate激活成功后命令行前面会出现(venv)标记。然后在虚拟环境里安装 Djangopip install django安装完成后检查版本python -m django --version能看到版本号说明 Django 安装成功。3.4 开发环境配置建议编辑器开启Python扩展和Django模板语法高亮扩展。如果使用 VS Code可以在项目根目录创建.vscode/settings.json把 Python 解释器指向虚拟环境路径。使用 PyCharm 的话创建项目时直接选择虚拟环境即可图形化操作对新手更友好。环境准备到这里就够了。不需要提前配数据库Django 默认使用 SQLite零配置直接可用。4. 创建 Django 项目与应用这是新手第一次接触 Django 目录结构的关键步骤。记住一个核心概念项目Project是一个网站的整体配置应用App是网站里一个具体的功能模块。一个项目可以包含多个应用。4.1 创建项目进入你打算存放代码的目录执行django-admin startproject myblog这里的myblog是项目名。执行后会生成如下结构myblog/ manage.py myblog/ __init__.py settings.py urls.py asgi.py wsgi.py重点说明manage.py项目的命令行管理工具启动服务器、执行数据库迁移都靠它。settings.py全局配置文件包括数据库、应用注册、静态文件路径等。urls.py全局 URL 路由入口所有请求都会先经过这里。asgi.py和wsgi.py部署时使用的服务器入口开发阶段不用管。4.2 创建应用进入项目目录cd myblog python manage.py startapp blogblog就是这个项目里的一个应用。生成结果blog/ __init__.py admin.py apps.py models.py tests.py views.py migrations/ __init__.py新手阶段重点关注三个文件models.py定义数据库表结构。views.py写业务逻辑处理 HTTP 请求。admin.py注册模型到 Admin 后台。4.3 将应用注册到项目打开myblog/settings.py在INSTALLED_APPS列表中添加blogINSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, blog, # 新增这一行 ]这一步不做后面创建的模型和 Admin 页面不会生效。4.4 启动开发服务器验证回到项目根目录执行python manage.py runserver看到类似下面的输出说明项目已经跑起来了Starting development server at http://127.0.0.1:8000/浏览器访问http://127.0.0.1:8000/如果出现 Django 默认的“Congratulations”页面说明环境完全正常。此时你就已经走通了 Django 主线中的第一步项目能启动Django 能接收 HTTP 请求。5. 功能测试与效果验证从 URL 到视图环境跑通之后接下来要做的第一件正经事是让 Django 返回一个由我们自己写的页面。5.1 编写第一个视图函数打开blog/views.py写入from django.http import HttpResponse def index(request): return HttpResponse(你好Django这是我的第一个页面。)这里先不涉及模板和数据库只返回最简单的文本。目的是验证 URL 配置和视图函数的调用链路是否通畅。5.2 配置 URL 路由Django 的请求处理第一站是项目的urls.py。打开myblog/urls.py把请求分发到blog应用from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(blog.urls)), ]然后在blog应用目录下新建urls.py文件内容如下from django.urls import path from . import views urlpatterns [ path(, views.index, nameindex), ]这里path(, ...)表示访问根路径/时交给views.index处理。5.3 重启并验证如果runserver还开着保存代码后它会自动重载。在浏览器刷新http://127.0.0.1:8000/。预期结果页面显示“你好Django这是我的第一个页面。”5.4 判断是否成功的标准检查项预期结果页面是否显示自定义文本是终端是否有报错无修改views.py后刷新页面是否立即生效是这一步走通说明你已经理解了 Django 主线的关键一环URL - View。5.5 常见失败原因问题现象可能原因排查方式页面 404urls.py配置错误检查myblog/urls.py和blog/urls.py的路径参数页面 500视图函数有语法错误查看终端错误堆栈修改代码后没反应开发服务器未自动重载手动重启runserver6. 模型与 ORM让数据可以持久化Web 应用不会只返回固定文本。真实业务的核心是数据用户提交的内容要存下来页面展示的内容要从数据库读出来。这一节解决的就是“主线第 4 步操作数据库”。6.1 定义模型打开blog/models.py定义一个简单的文章模型from django.db import models class Article(models.Model): title models.CharField(max_length100, verbose_name标题) content models.TextField(verbose_name内容) created_at models.DateTimeField(auto_now_addTrue, verbose_name创建时间) def __str__(self): return self.title class Meta: verbose_name 文章 verbose_name_plural verbose_name每一行代码含义如下CharField短文本字段必须指定max_length。TextField长文本字段。DateTimeField(auto_now_addTrue)创建时自动记录当前时间。__str__Admin 后台和命令行中显示对象的名称。6.2 生成数据库迁移文件并执行迁移Django 用“迁移”机制把模型同步到数据库。执行两条命令python manage.py makemigrations python manage.py migratemakemigrations根据模型变化生成迁移文件存放在blog/migrations/。migrate把迁移文件真正执行到数据库。执行完成后Django 会自动创建数据表。使用默认 SQLite 时不需要任何额外配置数据库文件db.sqlite3会自动生成在项目根目录。6.3 用 ORM 增删改查Django 不要求你写 SQL。在 Python 命令行里执行以下操作即可完整验证 ORM 能力python manage.py shell这是一个交互式 Python 环境导入了 Django 的配置。依次输入# 新增一条数据 from blog.models import Article article Article(titleDjango 新手教程, content这是第一篇文章) article.save() # 查询所有数据 Article.objects.all() # 查询单条数据 a Article.objects.get(id1) # 修改数据 a.title Django 新手教程已修改 a.save() # 执行查询并过滤 Article.objects.filter(title__containsDjango) # 删除对象 a.delete()注意get(id1)只能返回一条记录如果多条记录匹配会报MultipleObjectsReturned没有匹配则报DoesNotExist。如果只是判断是否存在推荐使用.filter().exists()。用exit()退出 shell。6.4 判断 ORM 是否掌握你不需要背 API。只需要理解三个概念模型类等于数据库表类的属性对应表的字段。objects是模型管理器所有查询入口都从它开始。save()和delete()是写操作核心新增、修改都要先拿到对象再调用save()删除调用delete()。ORM 这条线走通你就能完成大部分日常数据操作。7. 模板与静态文件让页面真正可用数据已经能从数据库读写但用户看到的还是视图函数返回的纯文本。这一节走完主线第 5 步View - Template。7.1 创建模板目录在blog应用目录下新建templates/blog/目录。Django 会自动从每个应用的templates目录下寻找模板文件。新建blog/templates/blog/article_list.html!DOCTYPE html html langzh head meta charsetUTF-8 title文章列表/title /head body h1Django 文章列表/h1 ul {% for article in articles %} li{{ article.title }} - {{ article.created_at }}/li {% empty %} li暂无文章/li {% endfor %} /ul /body /html7.2 修改视图函数返回模板在blog/views.py中新增一个使用模板的视图from django.shortcuts import render from .models import Article def article_list(request): articles Article.objects.all().order_by(-created_at) return render(request, blog/article_list.html, {articles: articles})修改blog/urls.py新增路由urlpatterns [ path(, views.index, nameindex), path(articles/, views.article_list, namearticle_list), ]7.3 验证模板渲染浏览器访问http://127.0.0.1:8000/articles/。如果之前用 ORM 添加过数据页面会显示文章标题和创建时间。如果没数据会显示“暂无文章”。到这里你可以先回http://127.0.0.1:8000/的根路径。此时再把views.index改成调用article_list视图让首页直接展示文章列表from django.shortcuts import render from .models import Article def index(request): articles Article.objects.all().order_by(-created_at) return render(request, blog/article_list.html, {articles: articles})刷新首页你会发现主线全部串起来了浏览器请求根路径/。myblog/urls.py把请求分发给blog/urls.py。blog/urls.py匹配到views.index。index视图从数据库读取文章列表。模板渲染数据。Django 返回完整 HTML 页面。这就是整个 Django 的核心主线。7.4 静态文件配置开发阶段默认的静态文件配置已经写好不需要额外修改。在blog/templates/blog/下再建一个static/blog/目录放入style.css然后在模板顶部加载{% load static %} !DOCTYPE html html langzh head meta charsetUTF-8 title文章列表/title link relstylesheet href{% static blog/style.css %} /head具体样式可以自行编写。只需要知道模板中要用{% static %}标签引用静态文件Django 会自动拼接静态文件路径。8. Admin 后台零代码生成管理界面Django 的 Admin 后台是它最吸引新手的特性之一。你只需要写几行代码就能得到一个支持增删改查的完整管理界面。8.1 创建超级用户在命令行执行python manage.py createsuperuser按提示输入用户名、邮箱、密码。密码至少 8 位不要设置太简单。8.2 注册模型到 Admin打开blog/admin.pyfrom django.contrib import admin from .models import Article admin.register(Article) class ArticleAdmin(admin.ModelAdmin): list_display [id, title, created_at] search_fields [title]list_display指定列表页显示的字段search_fields开启搜索框。8.3 访问后台并验证启动服务器后浏览器访问http://127.0.0.1:8000/admin/输入超级用户账号登录。预期效果页面显示“文章”模块。可以点击“增加”新建文章。可以编辑、删除文章。列表页显示标题和创建时间右上角有搜索框。这一步完成你的第一个 Django 项目已经具备“写文章 - 存数据库 - 页面展示 - 后台管理”的完整闭环。8.4 注意 Admin 的边界Admin 后台适合内部管理、运营编辑、数据维护不适合直接给普通用户当前台使用。它的设计目标是给管理员用的工具界面不是面向终端用户的产品界面。如果要给用户使用需要自定义视图和模板或者使用 Django REST Framework 开发 API 接口。9. 接口 API 与批量任务扩展如果你需要把 Django 的能力开放给其他系统或者做前后台分离最常用的方案是 Django REST FrameworkDRF。9.1 安装 DRF在虚拟环境中安装pip install djangorestframework在settings.py的INSTALLED_APPS中添加rest_framework,9.2 创建序列化器在blog应用下新建serializers.pyfrom rest_framework import serializers from .models import Article class ArticleSerializer(serializers.ModelSerializer): class Meta: model Article fields [id, title, content, created_at]9.3 创建 API 视图在blog/views.py中添加from rest_framework.decorators import api_view from rest_framework.response import Response from .serializers import ArticleSerializer api_view([GET, POST]) def article_api(request): if request.method GET: articles Article.objects.all() serializer ArticleSerializer(articles, manyTrue) return Response(serializer.data) elif request.method POST: serializer ArticleSerializer(datarequest.data) if serializer.is_valid(): serializer.save() return Response(serializer.data, status201) return Response(serializer.errors, status400)在blog/urls.py添加路由path(api/articles/, views.article_api, namearticle_api),9.4 测试 API启动服务后访问http://127.0.0.1:8000/api/articles/浏览器会显示 JSON 数据。也可以使用命令行测试curl http://127.0.0.1:8000/api/articles/用 POST 新增一篇curl -X POST http://127.0.0.1:8000/api/articles/ \ -H Content-Type: application/json \ -d {title: API 示例, content: 通过接口创建}9.5 批量任务建议Django 里做批量任务有两种推荐方式简单场景写 Django Command用python manage.py my_command执行适合定时脚本、数据清洗、邮件发送。复杂场景接入 Celery Redis适合异步任务、长耗时任务、需要重试机制的任务队列。新手阶段优先用 Django Command 解决问题它零依赖、易调试。等任务量大了再考虑 Celery。10. 常见问题与排查方法以下是新手使用 Django 时最常遇到的问题建议直接收藏作为排查手册问题现象可能原因排查方式解决方案pip install django报错网络问题或 Python 版本过低查看错误信息最后几行换国内 pip 源后重试django-admin不是内部或外部命令虚拟环境未激活命令行提示符前是否有(venv)执行虚拟环境激活命令页面 404URL 路由不匹配检查urls.py中的路径参数对比浏览器地址和path参数页面 500视图或模型代码报错查看终端完整报错堆栈根据堆栈定位到具体文件和行号数据库操作报no such table忘记执行migrate查看blog/migrations目录执行python manage.py migrateAdmin 后台登录后是英文本地化配置未打开打开settings.py设置LANGUAGE_CODE zh-hans修改models.py后查不到新字段未生成迁移文件查看迁移目录执行makemigrations后再migrate端口被占用其他程序已使用 8000 端口查看终端报错信息更换端口python manage.py runserver 8001模板变量不显示变量名或上下文键名不一致对比视图传入的字典键和模板中的变量名确保两者完全一致API 返回 403Django 的 CSRF 校验检查请求方式和 Django 配置开发阶段可在视图上加csrf_exempt但不推荐在生产使用migrate后项目启动变慢数据库连接或迁移历史过多观察启动日志正常现象首次迁移后启动速度会恢复另外两个常见场景依赖安装失败建议全程使用虚拟环境并且使用 Python 3.9 以上版本避免版本兼容性问题。显存或资源占用问题Django 本身是 Web 框架不涉及 GPU 推理资源占用以内存为主。开发服务器是单线程的只用于本地开发不要直接用于生产环境。11. 最佳实践与使用建议学 Django 的正确姿势不是把所有文档读完而是尽快完成一个最小闭环。建议按这个顺序推进第一个项目不要复杂。做一个“个人名片页 留言板”就够了前端页面展示个人信息留言板存数据库Admin 后台管理留言。这个项目包含 Django 的完整主线又不会让你陷入复杂的业务逻辑。代码组织上坚持一条原则业务逻辑写进视图或独立的 service 层不要在模板里写复杂逻辑。模板只负责展示查询逻辑放视图层数据处理放模型方法或独立工具模块。虚拟环境一定要用。一个项目对应一个虚拟环境后期部署到服务器时用pip freeze requirements.txt导出依赖在服务器上执行pip install -r requirements.txt就能复现环境。数据库切换要趁早。SQLite 虽然零配置但生产环境部署建议换用 PostgreSQL 或 MySQL。切换时只需修改settings.py中的数据库配置ORM 代码不用改这也正是 Django 的优势。文件目录提前规划。建议按照业务的自然边界拆分应用例如用户相关一个 App、文章相关一个 App。不要把所有模型塞进同一个 App否则项目变大后非常难维护。安全方面要注意开发环境把DEBUG True打开方便排查问题部署到生产环境必须把DEBUG设为False同时修改ALLOWED_HOSTS否则会出现安全提示。涉及用户上传文件、权限管理、支付回调等场景一定要先看 Django 官方安全文档。12. 下一步能做什么主线走通之后你的能力边界已经打开。下一步可以根据自己的方向选择想做标准业务后台学习分页、表单验证、消息通知、用户权限管理。想做前后端分离深入学习 Django REST Framework把重点放在序列化器、认证权限、视图集和路由上。想部署上线学习 Gunicorn Nginx 的部署方案配置静态文件收集使用 PostgreSQL 替换 SQLite。想处理异步任务把 Celery 接进来用 Redis 做消息队列。想学其它 Python Web 框架可以对比学习 Flask 或 FastAPI那时你会发现 Django 的“全家桶”设计思路和微框架是完全不同的两种风格。最后给一个很实际的小建议给自己留一个“最小可运行项目”目录里面保存环境创建命令、项目初始化命令、核心示例代码。当你学新知识点时在这个最小项目上做实验比每次新建项目快得多也比看文档印象深。第一次完整跑通 Django 之后后面每一个新功能都只是往这个骨架上加肌肉而已。
