Skip to content

1. 简介

本文档的 PDF 在 |这里|。

本文档的代码在 |这里|。

本文档是 Anthropic 的 AI Claude 的作品。它承接文档 《[Symfony] Web 框架分步入门》(2026 年),后者又承接了文档 《[Laravel] Web 框架分步入门》、《[Flask] Web 框架分步入门》、《[Spring MVC] Web 框架分步入门》、《[ASP.NET Core MVC] Web 框架分步入门》以及“[NestJS] Web 框架分步入门”(2026 年)。本文档告别 [PHP] 世界,回到 [Python] 语言,即 [Flask] 课程所用的语言,但框架的规模完全不同:

  • [Symfony] 框架被 [Django] 6.1 框架取代,使用 [Python] 语言(3.12 或更高版本);
  • [Twig] 视图被 [Django] 模板取代,模板使用其模板语言 DTL(Django Template Language)编写;
  • [Symfony] 的 Form 和 Validator 组件被 [Django] 的表单([django.forms] 模块)取代,它同时描述 HTML 表单的字段、字段的转换以及验证;
  • [Symfony] 的 Security 组件(防火墙、认证器、角色)被专为此目的编写的中间件和装饰器取代,其中 JWT 令牌使用 [PyJWT] 库,密码使用 [bcrypt] 库;
  • [Symfony] 的事件监听器被 [Django] 的中间件(它包裹每个请求的处理过程)和信号取代;
  • ORM 被 [Django] 的 ORM 取代,底层仍然基于 [MySQL]。

本文档紧密遵循 [Symfony] 课程的结构:先是大量小项目,每个项目只聚焦一个概念,然后是一个完整的案例研究——一个用于医疗诊所预约安排的 Web 应用——所有文件都有完整注释。这些示例的编号和涵盖的主题与 [Symfony]、[Laravel]、[Flask]、[Spring MVC] 和 [ASP.NET Core MVC] 课程中相同:熟悉其中任何一门课程的读者可以逐个示例地比较这些框架。不过这并非必需:本文档自成一体,不要求读者事先了解这些框架。唯一的先决条件是 Web 编程的基本知识(HTTP 协议、HTML 语言)以及 [Python] 语言的基础(变量、列表、字典、函数、类、模块)。示例中使用的 [Python] 较不常见的特性(装饰器、数据类、类型注解、上下文管理器、生成器等)会在首次出现时加以解释。

1.1. Django 在 Web 应用中的角色

Web 应用通常按层构建,每一层只与其相邻的层通信:

Image

  • Web 层接收来自浏览器的 HTTP 请求,并向浏览器返回 HTML 页面。这一层正是 [Django] 帮助我们编写的部分;
  • 业务层包含应用的业务规则(例如“一位患者同一时间只能有一个未来的预约”)。它对 Web 一无所知:它同样可以为命令行应用提供服务;
  • 数据访问层(DAO 层,DAO 即 Data Access Object)负责读写数据库。我们将使用 [Django] 的 ORM(Object Relational Mapper,对象关系映射器),它把表中的行映射为 [Python] 对象。

Web 层本身遵循 MVC(Model-View-Controller,模型-视图-控制器)模式。这里需要留意术语,因为 [Django] 并不按通常的含义使用 MVC 的术语。[Django] 的文档称其为 MTV 架构(Model–Template–View):

  • MVC 所说的控制器(C),[Django] 称为视图:它是一个 [Python] 函数(或类),负责处理某一类请求(例如 [GET /schedule])。视图读取请求参数,调用业务层,然后选择要显示的页面。在 [Symfony] 课程中,这对应控制器的一个动作;
  • MVC 所说的视图(V),[Django] 称为模板:它是一个 HTML 文件,其中包含表达式 [{{ ... }}] 和指令 [{% if %}]、[{% for %}]……,模板引擎会用数据替换它们。在 [Symfony] 课程中,它是一个视图([Twig]);
  • MVC 所说的模型(M)——传递给页面的数据集合——[Django] 称为模板上下文:一个 [Python] 字典;
  • 最后,[Django] 所说的模型是一个 [Python] 类,它表示一张数据库表(文件 [models.py]):这相当于 [Symfony] 过去所说的实体。

本文档采用 [Django] 的术语,因为其文档、错误消息和文件名([views.py]、[templates]、[models.py])使用的都是这套术语:因此,在这里视图始终是处理请求的 [Python] 函数,模板则是生成页面的 HTML 文件。“模型”一词有两种含义,上下文总能将它们区分开:在第 2 章中,视图的模型指它从请求中接收的数据,由一个类来描述;从第 7 章起,[Django] 的模型是一个 ORM 类。最后,“页面模板”(或“布局”)一词指其他页面所继承的公共模板(示例 15)。

请求的处理遵循图中编号的步骤:

  • 1:浏览器发送请求,例如 HTTP;
  • 2:Web 服务器接收请求,并通过 [Django] 应用在 [application] 文件 [config/wsgi.py] 中的对象将请求交给它。开发期间,这个服务器是 [Django] 自带的服务器,由命令 [python manage.py runserver] 启动;在生产环境中,它将是一个 [Python] 服务器,例如 [gunicorn] 或 [waitress],通常置于 [nginx] 之类的 Web 服务器之后。[Django] 让请求依次经过一系列中间件组件([Django] 的类以及应用自己的类,它们在视图之前和之后介入:会话管理、防 CSRF 保护、语言设置、安全等),并将请求的路径与应用的路由(在 [urls.py] 文件中描述)进行比较,以选出负责处理该请求的视图:这就是路由;
  • 3:视图向业务层请求它所需的数据;业务层在必要时联系 DAO 层,DAO 层通过 ORM 以 SQL 查询 [MySQL] 数据库;
  • 4:视图构建上下文(M 模型),并指示模板引擎生成页面(函数 [render]);
  • 5:由模板生成的 HTML 页面就是视图的响应,[Django] 在让它再次经过中间件之后将其返回给浏览器。

[Django] 与 [Flask] 一道,是 [Python] 世界中两大主要 Web 框架之一。它免费开源,由 Adrian Holovaty 和 Simon Willison 于 2003 年在堪萨斯州的报纸 Lawrence Journal-World 创建,2005 年发布,名称取自爵士吉他手 Django Reinhardt。如今它由社区在 Django Software Foundation 的支持下开发,凡是 [Python] ([Windows]、[Linux]、[macOS])能运行的地方,它都能运行。高流量网站也在使用它([Instagram]、[Pinterest]、[Mozilla]……)。它的座右铭“为有截止日期的完美主义者打造的 Web 框架”清楚地体现了其思路:[Flask] 只提供一个核心,再用扩展来补充,[Django] 则“自带电池”:路由、模板、表单与验证、ORM 和数据库迁移、会话、消息、翻译、缓存、针对常见攻击(CSRF、SQL 注入、点击劫持)的防护,甚至还有自动生成的数据管理界面。这一切构成一个紧密结合、在同一处有完整文档、并被设计为协同工作的整体。与 [Symfony] 相比,[Django] 做出了不同的选择:没有服务容器和依赖注入,而是使用被导入的 [Python] 模块;配置用 [Python] 编写,集中在单个文件([settings.py])中,而不是写在 [YAML] 里;视图就是简单的函数。[Django] 还遵循规律的发布节奏:大约每八个月发布一个版本,每两年发布一个“长期支持”(LTS)版本(2025 年的 5.2、2027 年的 6.2),并且在移除某项功能之前,总会提前两个版本发出弃用通知。[Django] 可以创建向 [JavaScript] 客户端([Angular]、[React]、[Vue.js]、[Flutter]……)返回 JSON 的服务器,通常借助扩展 [Django REST framework],这不同于传统 Web 应用:在传统应用中,由服务器生成 HTML 页面,浏览器只负责显示。本文档探讨的是后一种用例。

与 [PHP] 的一个关键差异,在很大程度上解释了 [Django] 的许多特点:应用在服务器启动时加载一次,之后一直驻留在内存中处理所有后续请求(示例 01)。启动时构建的内容(配置、路由表、存放在模块变量中的对象)由所有请求共享。这与 [Symfony] 相反,后者在每个请求时都重新构建应用:我们会经常回到这一点,尤其是在数据作用域那一章。

1.2. 所用工具

示例是使用以下工具编写和测试的(安装方法见附录):

  • [Python] 3.13(任何 3.12 或更高版本均可:这是 [Django] 6.1 的最低要求);
  • [pip],[Python] 的库管理器,以及用于创建虚拟环境的 [venv] 模块(两者都随 [Python] 一起提供);
  • [Visual Studio Code] 编辑器,以及 Microsoft 的扩展 [Python] 和 [Pylance] (代码分析、运行、调试),还有一个用于 [Django] 模板的扩展(语法高亮);
  • 一款现代浏览器([Chrome]、[Firefox]、[Edge]);
  • 命令行工具 [curl],它可以显示原始的 HTTP 响应([Windows] 10 和 11 已自带);
  • SGBD [MySQL] 8.4 或更高版本(或 [MariaDB] 10.11 或更高版本),例如 [Laragon] 在 [Windows] 下提供的版本,从数据访问那一章开始以及案例研究中使用。

[Django] 和其他库并不属于 [Python]:[pip] 会在安装时从 PyPI 仓库(Python Package Index)下载它们(因此当天必须连接互联网),并把它们安装到虚拟环境中,即项目专属的文件夹(见下文)。每个项目在 [requirements.txt] 文件中描述它所用的库。下表列出了主要的库及所用版本:

库
作用
版本
[Django]
框架本身:开发服务器、路由、视图、中间件、模板、表单、会话、消息、翻译、缓存、ORM;它会安装自己需要的两个库:[asgiref] (同步代码与异步代码之间的桥梁)和 [sqlparse] (格式化所显示的 SQL 语句)
6.1.1
[Babel]
按语言格式化数字、金额和日期(示例 16)
2.18.0
[PyJWT]
JWT 令牌(身份验证一章)
2.15.0
[mysqlclient]
[MySQL] 驱动程序,供 [Django] 使用(示例 28 和案例研究)
2.3.0
[bcrypt]
密码哈希(案例研究)
5.0.0

[Django] 通常通过 [pip] 安装,然后使用 [django-admin startproject] 命令创建项目,该命令由 [Django] 安装(见附录):

pip install django
django-admin startproject my_project

该命令会创建一个名为 [my_project] 的文件夹,其中包含一个名为 [manage.py] 的文件和一个名为 [my_project] 的包,该包由五个文件组成([settings.py]、[urls.py]、[wsgi.py]、[asgi.py]、[__init__.py])。随后使用 [python manage.py startapp name] 命令添加应用,该命令会创建一个包含七个文件的文件夹。真正的项目就是这样开始的。就学习而言,这种方式有一个缺点:生成的文件 [settings.py] 已经包含大约一百行代码,它们激活了大约十个应用和七个中间件组件——而这些的用途目前还不清楚。因此,本文档的示例从另一端开始:示例 01 是尽可能小的 [Django] 应用,每个示例只添加它所需的文件和设置,并由手工编写和注释。末尾的案例研究遵循标准 [Django] 应用的结构。

1.3. 运行案例研究

1.3.1. 安装 Laragon

案例研究需要 SGBD [MySQL]。Laragon 可以提供它,而且不止于此。截至 2026 年 9 月,Laragon 可在 URL 和 [Download Laragon – Fast & Modern Dev Environment] 获取。Laragon 包含一些工具,可用来安装 Web 服务器和 SGBD 以及 [MySQL]:

Image

  • 在 [1] 处,是 Apache Web 服务器;
  • 在 [2] 处,是 SGBD [MySQL];
  • 在 [3] 处,是一个我们不会使用的邮件工具;
  • [4] 启动所有服务(Apache、[MySQL]、MailPit);
  • [5] 显示 URL 和 [http://localhost] 对应的网页。默认情况下,该 URL 指向 <laragon-install>\www 文件夹,其中 <laragon-install> 是 Laragon 的安装文件夹;
  • 在 [6] 处,启动 HeidiSQL 工具,它可以管理 MySQL 数据库。我们将用这个工具创建案例研究所用的数据库;
  • 在 [7] 处,打开一个终端,Laragon 所需的所有二进制文件都在该终端的 PATH 中;
  • 在 [8] 处,打开一个 Windows 资源管理器窗口,位于与 URL 和 [http://localhost] 关联的文件夹中;

Laragon 的安装文件夹包含以下内容:

Image

在 [1] 处,[bin] 文件夹包含许多应用程序:

Image

  • 在 [1] 处,是 Apache Web 服务器;
  • 在 [2] 处,是命令行终端;
  • 在 [3] 处,是 [git] 客户端,可用来管理项目的不同版本;
  • 在 [4] 处,是数据库管理器;
  • [5],是邮件管理器;
  • 在 [6] 处,是 SGBD 和 [MySQL];
  • [7],是另一个 Web 服务器;
  • 在 [8] 处,是用于运行 JavaScript 脚本的 [node.js] ;
  • [9],是文本编辑器;
  • [10],是 PHP 解释器;
  • [11],是 [Python] 解释器;
  • [12],是缓存服务器;

Laragon 自带一个完整的开发环境。在本课程中,我们只使用 SGBD [MySQL], [6], 以及用于以图形方式管理它的 [heidisql] 工具。Laragon 的 [Python] [11] 解释器对于 [Django] 6.1 来说可能不够新(需要 3.12 或更高版本):因此我们将从官方网站安装 [Python] (见附录),并在安装程序中勾选把 [python] 添加到机器现有 PATH 的选项。

案例研究中提到的 README 指出,必须在应用所在文件夹中打开的终端窗口里输入以下命令:

python -m venv .venv

创建一个名为 [Python] 虚拟环境,以及一个名为 [.venv] 的文件夹,应用的库将安装在其中;

.venv\Scripts\activate

在终端中激活这个环境(在 [Linux] 和 [macOS] 下:[source .venv/bin/activate])。此后终端提示符以 [(.venv)] 开头;

pip install -r requirements.txt

安装案例研究所需的 [Python] 库([Django]、[mysqlclient]、[PyJWT]、[bcrypt]);

python manage.py runserver 8081

运行案例研究。如果你在 VSCode 中使用 [PowerShell] 终端,[PowerShell] 可能会拒绝运行激活脚本,并显示一条消息,说明“在此系统上禁止运行脚本”。要启用它,仅针对你的用户账户,请在 [PowerShell] 终端中执行一次以下命令:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

你需要重启 VSCode,此更改才会生效。或者,在 VSCode 中,你可以选择名为 [Command Prompt] 的终端来代替 [PowerShell],在其中脚本 [activate] 无需此授权即可运行。

要创建案例研究所需的 [MySQL] 数据库,请按以下步骤操作:

Image

  • 在 [1] 处,必须启动所有服务;
  • 在 [2] 处,[Database] 选项可用来管理数据库;

选项 [Database] 会启动一个名为 HeidiSQL 的实用工具:

Image

  • 在 [1] 处,可以选择各种 SGBD 选项。默认值为 SGBD MySQL,这没有问题;
  • 在 [2] 处,登录 HeidiSQL;

Image

Image

  • 在 [1-2] 处,运行 SQL 文件,然后选择文件 [dbrdvmedecins2.sql], 它位于文件夹 [django-sept-2026/rdvmedecins2-django/database] 中:

Image

运行 [3] 处的文件将创建案例研究所用的 [dbrdvmedecins2] 数据库。要查看它,请在 HeidiSQL 中按 F5 刷新显示。

注意:下面的截图显示的是名为 [dbrdvmedecins] 的数据库,而案例研究所用的数据库名为 [dbrdvmedecins2]。这两个数据库几乎完全相同,因此我们认为没有必要重新截图。

Image

数据库 [dbrdvmedecins] 已经创建。其内容如下:

Image

  • 在 [1-3] 处,是表 [clients];
    • [id] 是该表的主键;
    • [version] 是该行的版本号。该行每被修改一次,这个数字就加 1;
    • [titre, nom, prenom] 用于标识该人员;

Image

  • 在 [1-3] 处,是表 [medecins];
    • [id] 是该表的主键;
    • [version] 是该行的版本号;
    • [titre, nom, prenom] 用于标识该人员;

Image

  • 在 [1-3] 处,是医生预约时间段的表:
    • [id]:主键;
    • [version]:行的版本号;
    • [id_medecin]:外键,引用医生的主键;
    • [hdebut, mdebut]:预约开始时间的小时和分钟。因此,[8,20] 表示上午 8:20。
    • [hfin, mfin]:诊疗结束时间的小时和分钟。

Image

  • 在 [1-3] 处,是已安排预约的 [rv] 表;
    • [id]:主键;
    • [version]:版本号;
    • [jour]:预约日期;
    • [id_creneau]:外键,引用预约时间段的主键。由于时间段与某位医生关联,因此我们能知道由哪位医生负责这次预约;
    • [id_client]:外键,指向提出预约的客户的编号(主键);

Image

  • 在 [1-3] 处,是表 [users], 它列出了被授权使用该应用的用户;
    • [id, version]:主键、版本号;
    • [login, password]:用户凭据;
    • [nom]:用户名称;
    • [role]:用户的角色。[ADMIN] 拥有完全访问权限;[MEDECIN] 查看自己的日程;[PATIENT] (诊所的客户)安排和取消自己的预约;

1.3.2. 执行案例研究

审校者的话:我建议读者立即按下文所述执行案例研究。一旦你完全理解了这个预约应用的作用,就请你喜欢的 AI 按如下方式修改该应用:今后,每位医生都可以:

  • 在两个日期之间设置自己的诊疗时间段。这样他们就可以根据需要调整自己的日程;
  • 从日历中移除某一天的某些时间段——例如,当他们因个人原因无法出诊时;

这一修改并不简单,因为它涉及数据库结构的变更。请让 AI 为你提供新的应用代码以及用于创建新数据库的 SQL 脚本。为此,你需要向它提供包含完整项目的 ZIP 文件以及旧数据库的 SQL 脚本。

另外,我没有审阅 Claude 创建的这门课程。他此前已经制作了 [NestJS]、[ASP.NET Core MVC]、[Spring MVC] 和 [Flask] 课程,它们都很完美。我假定这一门也是如此。如果你在理解某些内容时遇到问题,解决办法始终相同:请你喜欢的 AI 解释你不理解的地方。例如,Claude 就非常擅长这一点。你可能需要把你不理解的示例“上传”给它。

注记结束。

本文档末尾的案例研究是一个完整的应用。读者很可能希望在深入框架细节之前先看到它的实际运行效果:下面介绍如何运行它。它位于 [rdvmedecins2-django] 文件夹中,与 [examples] 文件夹并列:

1
2
3
django-sept-2026/
├── examples/
└── rdvmedecins2-django/

你必须已经安装了 [Python] (3.12 或更高版本)、[Visual Studio Code], 以及 [MySQL] (见附录)。然后:

  • 通过运行 [dbrdvmedecins2] 脚本 [rdvmedecins2-django/database/dbrdvmedecins2.sql] 来创建数据库。使用 [Laragon] 时,打开 [HeidiSQL] 工具(Database 按钮),然后通过 File / Run SQL 菜单运行该脚本(见上文)。在命令行中,从 [rdvmedecins2-django] 文件夹执行:
mysql -u root < database/dbrdvmedecins2.sql
  • 在 [rdvmedecins2-django] 文件夹中打开 [Visual Studio Code] (File 菜单 / Open Folder),然后打开一个终端(Terminal 菜单 / New Terminal);
  • 创建应用的虚拟环境并激活它,然后安装它的库:[pip] 读取文件 [requirements.txt],下载 [Django] 及其他库,并把它们放入应用的 [.venv] 文件夹(需要几十秒)。在 [Windows] 下:
1
2
3
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
  • 在 [Linux] 和 [macOS] 下,第二条命令是 [source .venv/bin/activate]。[Visual Studio Code] 会显示一个窗口,询问是否要为该文件夹使用这个环境:请接受;之后打开的任何终端都会自动激活它;
  • 检查与数据库的连接。应用连接到 [MySQL] 所在的 [127.0.0.1],端口 3306,使用用户 [root] ,不带密码([Laragon] 的默认设置)。如果你的 [root] 账户有密码,请把它填入应用的 [.env] 文件中 [DB_PASSWORD=] 所在的行;
  • 运行应用:
python manage.py runserver 8081
  • [Django] 显示:
1
2
3
4
5
6
7
8
Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
September 27, 2026 - 19:30:12
Django version 6.1.1, using settings 'config.settings'
Starting development server at http://127.0.0.1:8081/
Quit the server with CTRL-BREAK.

开发服务器正在监听本机的 8081 端口([127.0.0.1],即 [localhost])。收到的每个请求都会记录在控制台中,发送给数据库的 SQL 命令也一样;

  • 在浏览器中打开 URL [http://localhost:8081] :

Image

  • 使用某个演示账户登录,其密码与用户名相同:[admin] (管理员)、[pelissier]、[tatou]、[dupont] (医生)、[martin]、[durand]、[bistrou]、[german] (患者)。你还必须输入图片中的字符,大小写均可。

启动时,命令 [runserver] 会检查项目,并为此与 [MySQL] 一起连接数据库:如果数据库无法访问,服务器就不会启动,控制台会在一长串调用栈的末尾显示错误。如果消息是 [(2002, "Can't connect to server on '127.0.0.1' (10061)")],说明 [MySQL] 没有启动;如果是 [(1045, "Access denied for user 'root'@'localhost' (using password: NO)")],说明密码不正确;如果是 [(1049, "Unknown database 'dbrdvmedecins2'")],说明 SQL 脚本没有执行。如果 [python manage.py runserver] 命令失败并显示消息 [ModuleNotFoundError: No module named 'django'],说明虚拟环境没有启用(或者 [pip install] 没有执行);如果错误消息是 [Error: That port is already in use.],说明 8081 端口已被占用(例如被该应用的另一个版本占用)。应用的 [README.md] 文件描述了其他情形。在终端中使用 [Ctrl-C] 停止应用(在 [Ctrl-Pause] 下,即 [Windows],如 [Django] 的消息所述,但 [Ctrl-C] 也同样有效)。

一旦读者完全理解了这个预约应用的用途,就可以请他们喜欢的 AI 按如下方式修改它:今后,每位医生都可以:

  • 在两个日期之间设置自己的预约时间段。这样他们就可以根据需要调整自己的日程;
  • 从日历中移除某一天的某些时间段——例如,当他们因个人原因无法出诊时。

这一修改并不简单,因为它涉及数据库结构的变更。你必须向 AI 索取新的应用代码以及用于创建新数据库的 SQL 脚本,并向它提供包含完整项目的 ZIP 文件以及旧数据库的 SQL 脚本。同样,如果你在本文档中遇到不理解的地方,解决办法始终相同:请你喜欢的 AI 解释你不理解的内容,必要时把相关示例提供给它。

文档末尾的案例研究演示了如何使用该应用,然后逐个解释它的每个文件。

1.4. 示例

示例存放在 [examples] 文件夹中,每个示例对应一个子文件夹:

examples/
├── 01-structure/
├── 02-routing/
├── ...
├── 28-layers/
├── common/
│   ├── static/
│   │   └── bootstrap/
│   └── README.md
└── requirements.txt

每个示例都是一个可以独立运行的小应用([Django])。所有示例使用相同的库,它们在文件 [examples/requirements.txt] 中描述:

1
2
3
4
5
6
# 示例所用的库,一次性安装在示例文件夹的虚拟
# 环境中:pip install -r requirements.txt
Django==6.1.1
mysqlclient==2.3.0
PyJWT==2.15.0
Babel==2.18.0
  • 第 1–2 行:注释;在 [Python] 中,如本文件所示,注释从 [#] 开始,一直延伸到行尾;
  • 第 3–6 行:各个库,每行一个,带有精确版本:[Django] 本身、[mysqlclient] (访问 [MySQL],示例 28)、[PyJWT] (JWT 令牌,示例 25)以及 [Babel] (按语言格式化数字和日期,示例 16)。[==] 运算符强制指定版本;[>=6.1,<6.2] 则会接受所有 6.1.x 版本。[Django] 所需的两个库([asgiref]、[sqlparse])没有列出:[pip] 会自动安装它们,因为 [Django] 声明了这些依赖。

[Python] 每个解释器只识别一个库文件夹。为确保每个项目都拥有各自版本合适的库,需要创建虚拟环境:它是一个文件夹,包含解释器的轻量级副本及其自己的库文件夹([Lib/site-packages] 在 [Windows] 下,其他系统为 [lib/python3.13/site-packages] )。要运行这些示例,只需在打开到 [examples] 文件夹的终端中,一次性创建虚拟环境并在其中安装它们的库:

1
2
3
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

[python -m venv .venv] 执行 [venv] 模块,该模块来自 [Python],它在 [.venv] 文件夹中创建环境。脚本 [activate] (在 [Linux] 和 [macOS] 下:[source .venv/bin/activate])会修改终端的 PATH:此后命令 [python] 和 [pip] 指的就是环境中的那两个,并且提示符以 [(.venv)] 开头。[pip install -r requirements.txt] 会安装该文件中的库。[examples/.venv] 环境由全部 28 个示例共享:在每个要运行示例的终端中都要激活它。命令 [pip list] 显示已安装的库,[deactivate] 则停用该环境。[common] 文件夹包含 CSS 框架 [Bootstrap] ([common/static/bootstrap]),由那些对页面进行格式化的示例共享(从示例 15 开始)。

几乎所有示例都具有相同的结构——即标准 [Django] 项目的结构,并精简到只剩必要部分。例如示例 13 的结构:

13-first-view/
├── config/
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── pages/
│   ├── __init__.py
│   ├── urls.py
│   ├── viewmodels.py
│   └── views.py
├── templates/
│   └── pages/
│       ├── index.html
│       └── unknown.html
└── manage.py
  • [manage.py]:项目的命令行工具,尤其用于启动开发服务器(示例 01);
  • [config]:项目的配置包:包含其设置([settings.py])、路由([urls.py],示例 02)以及面向 Web 服务器的入口点([wsgi.py])。由 [django-admin startproject] 创建的项目会以项目名称命名这个包;为了阐明它的作用,我们在所有示例中都把它称为 [config] ;
  • [pages]:一个 [Django] 应用:它是一个 [Python] 包,汇集了视图([views.py])、它们的路由([urls.py])以及它们所需的类。项目是应用的集合,由 [INSTALLED_APPS] 设置列出(示例 02);
  • [templates]:模板(从模板那一章开始使用)。

要运行某个示例,请在其文件夹中打开终端(在 [Visual Studio Code] 中:右键单击示例文件夹,然后选择“Open in the built-in terminal”),激活示例的虚拟环境(在 [..\.venv\Scripts\activate] 下,即 [Windows],其他系统使用 [source ../.venv/bin/activate] ),然后输入:

python manage.py runserver

所有示例都监听 8000 端口:同一时间只能运行一个(否则必须更改端口:[python manage.py runserver 8001])。在终端中使用 [Ctrl-C] 停止服务器。修改 [Python] 文件或模板之后无需重启服务器:开发服务器会监视项目文件,其中任何文件发生变化时都会自动重启(示例 01)。

在 [Visual Studio Code] 中打开 [examples] 文件夹时,你必须为 [Python] 扩展指定虚拟环境的解释器(Python 命令:从命令面板选择 Select Interpreter,[Ctrl-Maj-P],然后 [.venv\Scripts\python.exe]):此后 [Pylance] 扩展会使用该环境的库(包括 [Django])分析所有文件:在每个文件中,你都可以使用代码补全、跳转到类或函数的定义([F12] 键)以及错误报告。由于所有示例都包含一个 [config] 包,分析时可能会把两个示例的包混淆;这对运行没有影响,因为每个示例都是在各自的文件夹中单独运行的。为避免这种混淆,只需直接打开示例自己的文件夹。

1.5. 文档内容

文档的组织如下:

章
主题
示例
视图、路由、响应
从请求到视图:路由、应用、响应、重定向、共享服务
01 至 06
视图模板
请求参数:读取、转换、通过 [Django] 表单进行验证、POST 请求
07 至 12
模板与表单
[Django] 模板语言、页面模板、片段、自定义标签和过滤器、表单、验证、PRG、防 CSRF 保护
13 至 21
国际化
法语和英语的应用
22
数据作用域
请求、会话、缓存、Cookie
23
请求的生命周期
信号、中间件、路由转换器、错误处理
24
身份验证与授权
Cookie 中的 JWT 令牌、身份验证中间件、装饰器、角色、验证码、尝试次数限制
25–27
分层架构与数据访问
使用 [Django] 的 ORM 和 [MySQL] 实现 Web / 业务 / DAO
28
案例研究
RdvMedecins 应用,逐个文件讲解
-

每个示例只引入少量新概念,各章相互衔接:最好按顺序阅读。相反,案例研究会用到前面各章的全部概念:只要相关,它的讲解就会指向引入该概念的示例。附录介绍了工具的安装:[Python]、[pip], 以及虚拟环境、[Visual Studio Code] 及其扩展、[MySQL] 以及 [Laragon]、[curl],还有 [django-admin] 工具。