Visual Studio Code 中的 Django 教程

Django 是一个高等级 Python 框架，专为快速、安全和可扩展的 Web 开发而设计。Django 包括对 URL 路由、页面模板和数据处理的丰富支持。

在本 Django 教程中，你将创建一个简单的 Django 应用，其中包含三个使用通用基本模板的页面。你将在 Visual Studio Code 的上下文中创建此应用，以了解如何在 VS Code 终端、编辑器和调试器中使用 Django。本教程不探讨有关 Django 本身的各种细节，例如处理数据模型和创建管理界面。有关这些方面的指导，请参阅本教程末尾的 Django 文档链接。

本 Django 教程的完整代码项目可以在 GitHub 上找到：python-sample-vscode-django-tutorial。

如果你有任何问题，可以在 Python 扩展讨论问答中搜索答案或提出问题。

先决条件

要成功完成本 Django 教程，你必须执行以下操作（与通用 Python 教程中的步骤相同）

安装 Python 扩展。
安装 Python 3 的版本（本教程是为此版本编写的）。选项包括
- （所有操作系统）从 python.org 下载；通常使用页面上首先出现的Download Python 3.9.1 按钮（或任何最新版本）。
- （Linux）内置的 Python 3 安装效果良好，但要安装其他 Python 包，你必须在终端中运行 sudo apt install python3-pip。
- （macOS）通过 macOS 上的 Homebrew 使用 brew install python3 进行安装（不支持 macOS 上的系统 Python 安装）。
- （所有操作系统）从 Anaconda 下载（用于数据科学目的）。
在 Windows 上，请确保 Python 解释器的位置包含在 PATH 环境变量中。你可以通过在命令提示符下运行 path 来检查位置。如果未包含 Python 解释器的文件夹，请打开 Windows 设置，搜索“环境”，选择编辑系统环境变量，然后编辑 Path 变量以包含该文件夹。

为 Django 教程创建项目环境

在本节中，你将创建一个虚拟环境，其中安装了 Django。使用虚拟环境可避免将 Django 安装到全局 Python 环境中，并使你可以精确控制应用程序中使用的库。虚拟环境还使你可以轻松地为环境创建 requirements.txt 文件。

在文件系统中，为此教程创建一个项目文件夹，例如 hello_django。
在该文件夹中，使用以下命令（根据你的计算机情况）基于当前解释器创建名为 .venv 的虚拟环境
```
# Linux
sudo apt-get install python3-venv    # If needed
python3 -m venv .venv
source .venv/bin/activate

# macOS
python3 -m venv .venv
source .venv/bin/activate

# Windows
py -3 -m venv .venv
.venv\scripts\activate
```
注意：运行上述命令时，请使用标准的 Python 安装。如果使用 Anaconda 安装中的 python.exe，你将看到一个错误，因为 ensurepip 模块不可用，并且环境处于未完成状态。
通过运行 code . 或运行 VS Code 并使用文件 > 打开文件夹命令，在 VS Code 中打开项目文件夹。
在 VS Code 中，打开命令面板（视图 > 命令面板或 (⇧⌘P (Windows、Linux Ctrl+Shift+P))）。然后选择 Python: 选择解释器 命令
该命令会显示 VS Code 可以自动找到的可用解释器列表（你的列表会有所不同；如果看不到所需的解释器，请参阅配置 Python 环境）。从列表中，选择项目文件夹中以 ./.venv 或 .\.venv 开头的虚拟环境
运行 终端: 创建新终端 (⌃⇧` (Windows、Linux Ctrl+Shift+`)) 从命令面板，这将创建一个终端并通过运行其激活脚本自动激活虚拟环境。

注意：在 Windows 上，如果你的默认终端类型是 PowerShell，你可能会看到一个错误，指出它无法运行 activate.ps1，因为系统上禁用了脚本运行。该错误提供了一个链接，其中包含有关如何允许脚本的信息。否则，请使用 终端: 选择默认配置文件 将“命令提示符”或“Git Bash”设置为默认值。
选定的环境会显示在 VS Code 状态栏的右侧，并注意到 ('.venv': venv) 指示器，它告诉你你正在使用虚拟环境
通过在 VS Code 终端中运行以下命令来更新虚拟环境中的 pip
```
python -m pip install --upgrade pip
```
通过在 VS Code 终端中运行以下命令在虚拟环境中安装 Django
```
python -m pip install django
```

现在你拥有一个独立的环境，可以编写 Django 代码了。当你使用 终端: 创建新终端 (⌃⇧` (Windows、Linux Ctrl+Shift+`)) 时，VS Code 会自动激活环境。如果打开单独的命令提示符或终端，请运行 source .venv/bin/activate (Linux/macOS) 或 .venv\Scripts\Activate.ps1 (Windows) 来激活环境。当命令提示符在开头显示 (.venv) 时，你就知道环境已激活。

创建并运行最小 Django 应用

在 Django 术语中，“Django 项目”由多个站点级配置文件以及一个或多个“应用”组成，你将这些“应用”部署到 Web 主机以创建完整的 Web 应用程序。一个 Django 项目可以包含多个应用，每个应用通常在项目中具有独立的功能，并且同一个应用可以存在于多个 Django 项目中。应用本身只是一个 Python 包，它遵循 Django 期望的某些约定。

因此，要创建一个最小的 Django 应用，首先需要创建 Django 项目作为应用的容器，然后创建应用本身。对于这两个目的，你都使用 Django 管理实用程序 django-admin，它在安装 Django 包时安装。

创建 Django 项目

在虚拟环境已激活的 VS Code 终端中，运行以下命令
```
django-admin startproject web_project .
```
此 startproject 命令假定（通过在末尾使用 .）当前文件夹是你的项目文件夹，并在其中创建以下内容
- manage.py：项目的 Django 命令行管理实用程序。你使用 python manage.py <command> [options] 为项目运行管理命令。
- 名为 web_project 的子文件夹，其中包含以下文件
  - __init__.py：一个空文件，告诉 Python 此文件夹是一个 Python 包。
  - asgi.py：与 ASGI 兼容的 Web 服务器用于服务你的项目的入口点。你通常将此文件保持原样，因为它为生产 Web 服务器提供了挂钩。
  - settings.py：包含 Django 项目的设置，你将在 Web 应用的开发过程中修改它。
  - urls.py：包含 Django 项目的目录，你也会在开发过程中修改它。
  - wsgi.py：与 WSGI 兼容的 Web 服务器用于服务你的项目的入口点。你通常将此文件保持原样，因为它为生产 Web 服务器提供了挂钩。
通过运行以下命令创建空的开发数据库
```
python manage.py migrate
```
首次运行服务器时，它会在文件 db.sqlite3 中创建一个默认的 SQLite 数据库，该数据库旨在用于开发目的，但也可以在生产环境中用于低流量 Web 应用。有关数据库的其他信息，请参阅数据库类型部分。
要验证 Django 项目，请确保你的虚拟环境已激活，然后使用命令 python manage.py runserver 启动 Django 的开发服务器。服务器在默认端口 8000 上运行，你会在终端窗口中看到如下输出
```
Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
June 13, 2023 - 18:38:07
Django version 4.2.2, using settings 'web_project.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CTRL-BREAK.
```
Django 的内置 Web 服务器仅用于本地开发目的。但是，当你部署到 Web 主机时，Django 将改用主机的 Web 服务器。Django 项目中的 wsgi.py 和 asgi.py 模块负责挂钩到生产服务器。

如果要使用与默认端口 8000 不同的端口，请在命令行上指定端口号，例如 python manage.py runserver 5000。
Ctrl+单击终端输出窗口中的 http://127.0.0.1:8000/ URL，以在默认浏览器中打开该地址。如果 Django 安装正确且项目有效，你将看到如下所示的默认页面。VS Code 终端输出窗口也会显示服务器日志。
完成后，关闭浏览器窗口并在 VS Code 中使用 Ctrl+C 停止服务器，如终端输出窗口中所示。

创建 Django 应用

在虚拟环境已激活的 VS Code 终端中，在你的项目文件夹（manage.py 所在的文件夹）中运行管理实用程序的 startapp 命令
```
python manage.py startapp hello
```
该命令创建一个名为 hello 的文件夹，其中包含多个代码文件和一个子文件夹。在这些文件中，你经常使用 views.py（其中包含定义 Web 应用中页面的函数）和 models.py（其中包含定义数据对象的类）。migrations 文件夹供 Django 的管理实用程序用于管理数据库版本，如本教程后面所述。还有文件 apps.py（应用配置）、admin.py（用于创建管理界面）和 tests.py（用于创建测试），此处未涵盖这些文件。

修改 hello/views.py 以匹配以下代码，这将为应用的主页创建一个视图

from django.http import HttpResponse

def home(request):
    return HttpResponse("Hello, Django!")

创建一个文件 hello/urls.py，其中包含以下内容。urls.py 文件是你指定模式以将不同的 URL 路由到其适当视图的位置。以下代码包含一个路由，用于将应用的根 URL ("") 映射到你刚刚添加到 hello/views.py 的 views.home 函数
```
from django.urls import path
from hello import views

urlpatterns = [
    path("", views.home, name="home"),
]
```
web_project 文件夹还包含一个 urls.py 文件，URL 路由实际上是在这里处理的。打开 web_project/urls.py 并对其进行修改以匹配以下代码（如果愿意，可以保留说明性注释）。此代码使用 django.urls.include 引入了应用的 hello/urls.py，这使应用的路由包含在应用中。当项目包含多个应用时，这种分离很有用。
```
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("", include("hello.urls")),
    path('admin/', admin.site.urls)
]
```
保存所有已修改的文件。
在 VS Code 终端中，再次激活虚拟环境，使用 python manage.py runserver 运行开发服务器，并打开浏览器访问 http://127.0.0.1:8000/，以查看呈现“Hello, Django”的页面。

创建调试器启动配置文件

你可能已经在想，是否有一种更简单的方法来运行服务器和测试应用，而无需每次都键入 python manage.py runserver。幸运的是，确实有！你可以在 VS Code 中创建一个自定义启动配置文件，该文件也用于不可避免的调试练习。

切换到 VS Code 中的运行视图（使用左侧活动栏或 F5）。你可能会看到消息“要自定义运行和调试，请创建一个 launch.json 文件”。这意味着你还没有包含调试配置的 launch.json 文件。如果单击创建 launch.json 文件链接，VS Code 可以为你创建该文件
选择该链接，VS Code 将提示你输入调试配置。从下拉列表中选择 Django，VS Code 将使用 Django 运行配置填充新的 launch.json 文件。launch.json 文件包含多个调试配置，每个配置都是 configuration 数组中的一个单独的 JSON 对象。

向下滚动并检查名称为“Python: Django”的配置

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python Debugger: Django",
      "type": "debugpy",
      "request": "launch",
      "program": "${workspaceFolder}\\manage.py",
      "args": ["runserver"],
      "django": true,
      "justMyCode": true
    }
  ]
}

此配置告诉 VS Code 使用选定的 Python 解释器和 args 列表中的参数运行 "${workspaceFolder}/manage.py"。然后，使用此配置启动 VS Code 调试器与在 VS Code 终端中使用激活的虚拟环境运行 python manage.py runserver 相同。（如果需要，可以将端口号（如 "5000"）添加到 args。）"django": true 条目还告诉 VS Code 启用 Django 页面模板的调试，你将在本教程的后面部分看到。

通过选择运行 > 启动调试菜单命令，或选择列表旁边的绿色启动调试箭头 (F5) 来测试配置
Ctrl+单击终端输出窗口中的 http://127.0.0.1:8000/ URL，以打开浏览器并查看应用是否正常运行。
完成后，关闭浏览器并停止调试器。要停止调试器，请使用“停止”工具栏按钮（红色方块）或运行 > 停止调试命令 (⇧F5 (Windows、Linux Shift+F5))。
现在，你可以随时使用运行 > 启动调试来测试应用，这样做的好处是还会自动保存所有已修改的文件。

探索调试器

调试使你有机会在特定的代码行上暂停正在运行的程序。当程序暂停时，你可以检查变量、在调试控制台面板中运行代码，以及利用调试中描述的功能。运行调试器还会在调试会话开始之前自动保存任何已修改的文件。

开始之前：确保你已在上节末尾使用终端中的 Ctrl+C 停止了正在运行的应用。如果将应用留在终端中运行，它将继续拥有该端口。因此，当你在调试器中使用同一端口运行应用时，原始正在运行的应用将处理所有请求，并且你不会在正在调试的应用中看到任何活动，程序也不会在断点处停止。换句话说，如果调试器似乎不起作用，请确保没有其他应用实例仍在运行。

在 hello/urls.py 中，向 urlpatterns 列表添加路由
```
path("hello/<name>", views.hello_there, name="hello_there"),
```
path 的第一个参数定义了一个名为“hello/”的路由，该路由接受名为 name 的变量字符串。该字符串传递给 path 的第二个参数中指定的 views.hello_there 函数。

URL 路由区分大小写。例如，路由 /hello/<name> 与 /Hello/<name> 不同。如果你希望相同的视图函数处理两者，请为每个变体定义路径。

将 views.py 的内容替换为以下代码，以定义你可以在调试器中单步执行的 hello_there 函数

import re
from django.utils.timezone import datetime
from django.http import HttpResponse

def home(request):
    return HttpResponse("Hello, Django!")

def hello_there(request, name):
    now = datetime.now()
    formatted_now = now.strftime("%A, %d %B, %Y at %X")

    # Filter the name argument to letters only using regular expressions. URL arguments
    # can contain arbitrary text, so we restrict to safe characters only.
    match_object = re.match("[a-zA-Z]+", name)

    if match_object:
        clean_name = match_object.group(0)
    else:
        clean_name = "Friend"

    content = "Hello there, " + clean_name + "! It's " + formatted_now
    return HttpResponse(content)

在 URL 路由中定义的 name 变量作为参数提供给 hello_there 函数。如代码注释中所述，始终筛选任意用户提供的信息，以避免对应用的各种攻击。在这种情况下，代码筛选 name 参数以仅包含字母，这避免了控制字符、HTML 等的注入。（当你使用下一节中的模板时，Django 会自动进行筛选，你不需要此代码。）

通过执行以下任一操作，在 hello_there 函数的第一行代码 (now = datetime.now()) 处设置断点
- 将光标放在该行上，按 F9，或者，
- 将光标放在该行上，选择运行 > 切换断点菜单命令，或者，
- 直接单击行号左侧的边距（当悬停在那里时，会出现一个褪色的红点）。
断点在左边距中显示为红点
通过选择运行 > 启动调试菜单命令，或选择列表旁边的绿色启动调试箭头 (F5) 启动调试器

观察状态栏颜色更改以指示调试

调试工具栏（如下所示）也会在 VS Code 中显示，其中包含以下顺序的命令：“暂停”（或“继续”，F5）、“单步跳过” (F10)、“单步调试” (F11)、“单步跳出” (⇧F11 (Windows、Linux Shift+F11))、“重启” (⇧⌘F5 (Windows、Linux Ctrl+Shift+F5)) 和“停止” (⇧F5 (Windows、Linux Shift+F5))。有关每个命令的说明，请参阅VS Code 调试。
输出显示在“Python 调试控制台”终端中。打开浏览器并导航到 http://127.0.0.1:8000/hello/VSCode。在页面呈现之前，VS Code 会在你设置的断点处暂停程序。断点上的小黄色箭头指示它是要运行的下一行代码。
使用“单步跳过”运行 now = datetime.now() 语句。
在 VS Code 窗口的左侧，你将看到一个变量窗格，其中显示了局部变量（如 now）以及参数（如 name）。下方是监视、调用堆栈和断点的窗格（有关详细信息，请参阅VS Code 调试）。在 局部变量 部分中，尝试展开不同的值。你还可以双击值（或使用 Enter (Windows、Linux F2)）来修改它们。但是，更改诸如 now 之类的变量可能会破坏程序。开发人员通常仅在代码最初没有生成正确的值时才进行更改以更正值。
当程序暂停时，调试控制台面板（与“终端”面板中的“Python 调试控制台”不同）使你可以使用程序的当前状态试验表达式并尝试少量代码。例如，在单步跳过行 now = datetime.now() 后，你可能会尝试不同的日期/时间格式。在编辑器中，选择读取 now.strftime("%A, %d %B, %Y at %X") 的代码，然后右键单击并选择调试: 计算以将该代码发送到调试控制台，在其中运行
```
now.strftime("%A, %d %B, %Y at %X")
'Friday, 07 September, 2018 at 07:46:32'
```
提示：调试控制台还显示来自应用内部的异常，这些异常可能不会显示在终端中。例如，如果你在运行和调试视图的调用堆栈区域中看到“在异常处暂停”消息，请切换到调试控制台以查看异常消息。

将该行复制到调试控制台底部的 > 提示符中，并尝试更改格式

now.strftime("%A, %d %B, %Y at %X")
'Tuesday, 13 June, 2023 at 18:03:19'
now.strftime("%a, %d %b, %Y at %X")
'Tue, 13 Jun, 2023 at 18:03:19'
now.strftime("%a, %d %b, %y at %X")
'Tue, 13 Jun, 23 at 18:03:19'

如果愿意，可以单步执行更多行代码，然后选择“继续” (F5) 以使程序运行。浏览器窗口显示结果
更改代码中的行以使用不同的日期时间格式，例如 now.strftime("%a, %d %b, %y at %X")，然后保存文件。Django 服务器将自动重新加载，这意味着更改将应用，而无需重启调试器。刷新浏览器上的页面以查看更新。
完成后，关闭浏览器并停止调试器。要停止调试器，请使用“停止”工具栏按钮（红色方块）或运行 > 停止调试命令 (⇧F5 (Windows、Linux Shift+F5))。

提示：为了更轻松地重复导航到特定 URL（如 http://127.0.0.1:8000/hello/VSCode），请在类似 views.py 的文件中使用 print 语句输出该 URL。URL 将显示在 VS Code 终端中，你可以在其中使用 Ctrl+单击在浏览器中打开它。

转到定义和速览定义命令

在 Django 或任何其他库的工作过程中，你可能希望检查这些库本身的代码。VS Code 提供了两个方便的命令，可以直接导航到任何代码中类和其他对象的定义

转到定义从你的代码跳转到定义对象的代码。例如，在 views.py 中，右键单击 home 函数中的 HttpResponse，然后选择转到定义（或使用 F12），这将导航到 Django 库中的类定义。
速览定义（⌥F12 (Windows Alt+F12, Linux Ctrl+Shift+F10)，也在右键单击上下文菜单中），与之类似，但直接在编辑器中显示类定义（在编辑器窗口中留出空间以避免遮盖任何代码）。按 Escape 关闭“速览”窗口或使用右上角的 x。

使用模板渲染页面

到目前为止，你在本教程中创建的应用仅从 Python 代码生成纯文本网页。尽管可以直接在代码中生成 HTML，但开发者会避免这种做法，因为它会使应用容易受到跨站脚本 (XSS) 攻击。例如，在本教程的 hello_there 函数中，有人可能会想到使用类似 content = "<h1>Hello there, " + clean_name + "!</h1>" 的代码来格式化输出，其中 content 中的结果直接提供给浏览器。这种做法允许攻击者在 URL 中放置恶意 HTML，包括 JavaScript 代码，最终出现在 clean_name 中，从而最终在浏览器中运行。

更好的做法是通过使用模板将 HTML 完全排除在代码之外，以便你的代码只关注数据值，而不关注渲染。

在 Django 中，模板是一个 HTML 文件，其中包含运行时代码提供的值的占位符。然后，Django 模板引擎负责在渲染页面时进行替换，并提供自动转义以防止 XSS 攻击（也就是说，如果你尝试在数据值中使用 HTML，你将看到 HTML 仅呈现为纯文本）。因此，代码只关注数据值，而模板只关注标记。Django 模板提供灵活的选项，例如模板继承，它允许你定义一个包含通用标记的基页，然后在此基础上构建特定于页面的添加内容。

在本节中，你将首先使用模板创建一个单页。在后续章节中，你将配置应用以提供静态文件，然后为应用创建多个页面，每个页面都包含来自基模板的导航栏。Django 模板还支持控制流和迭代，你将在本教程后面的模板调试上下文中看到。

在 web_project/settings.py 文件中，找到 INSTALLED_APPS 列表并添加以下条目，以确保项目知道该应用，以便它可以处理模板
```
'hello',
```
在 hello 文件夹内，创建一个名为 templates 的文件夹，然后再创建一个名为 hello 的子文件夹以匹配应用名称（这种两层文件夹结构是典型的 Django 约定）。
在 templates/hello 文件夹中，创建一个名为 hello_there.html 的文件，内容如下。此模板包含两个数据值的占位符，分别名为“name”和“date”，它们用花括号对 {{ 和 }} 划定。所有其他不变的文本都是模板的一部分，以及格式标记（例如 <strong>）。正如你所看到的，模板占位符也可以包含格式，管道符 | 符号后的表达式，在本例中使用 Django 的内置 date 过滤器和 time 过滤器。然后，代码只需要传递 datetime 值，而不是预格式化的字符串
```
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <title>Hello, Django</title>
    </head>
    <body>
        <strong>Hello there, {{ name }}!</strong> It's {{ date | date:"l, d F, Y" }} at {{ date | time:"H:i:s" }}
    </body>
</html>
```
在 views.py 的顶部，添加以下导入语句
```
from django.shortcuts import render
```
同样在 views.py 中，修改 hello_there 函数以使用 django.shortcuts.render 方法来加载模板并提供模板上下文。上下文是模板中使用的变量集。render 函数接受请求对象，后跟模板的路径相对于 templates 文件夹，然后是上下文对象。（开发者通常将模板命名为与使用它们的函数相同，但不需要匹配的名称，因为你始终在代码中引用确切的文件名。）
```
def hello_there(request, name):
    print(request.build_absolute_uri()) #optional
    return render(
        request,
        'hello/hello_there.html',
        {
            'name': name,
            'date': datetime.now()
        }
    )
```
你可以看到，代码现在简单得多，并且只关注数据值，因为标记和格式都包含在模板中。
启动程序（在调试器内部或外部，使用 ⌃F5 (Windows, Linux Ctrl+F5)），导航到 /hello/name URL，并观察结果。
还可以尝试使用类似 <a%20value%20that%20could%20be%20HTML> 的名称导航到 /hello/name URL，以查看 Django 的自动转义功能。 “name”值在浏览器中显示为纯文本，而不是呈现实际元素。

提供静态文件

静态文件是你的 Web 应用按原样返回某些请求的内容，例如 CSS 文件。提供静态文件需要 settings.py 中的 INSTALLED_APPS 列表包含 django.contrib.staticfiles，默认情况下已包含。

在 Django 中提供静态文件是一门艺术，尤其是在部署到生产环境时。此处显示的是一种简单的方法，它适用于 Django 开发服务器以及像 Gunicorn 这样的生产服务器。但是，对静态文件的完整处理超出了本教程的范围，因此有关更多信息，请参阅 Django 文档中的管理静态文件。

切换到生产环境时，导航到 settings.py，设置 DEBUG=False，并将 ALLOWED_HOSTS = ['*'] 更改为允许特定主机。当使用容器时，这可能会导致额外的工作。有关详细信息，请参阅问题 13。

准备应用以使用静态文件

在项目的 web_project/urls.py 中，添加以下 import 语句

from django.contrib.staticfiles.urls import staticfiles_urlpatterns

在同一个文件中，在末尾添加以下行，其中包括项目识别的标准静态文件 URL
```
urlpatterns += staticfiles_urlpatterns()
```

在模板中引用静态文件

在 hello 文件夹中，创建一个名为 static 的文件夹。
在 static 文件夹中，创建一个名为 hello 的子文件夹，与应用名称匹配。

这个额外的子文件夹的原因是，当你将 Django 项目部署到生产服务器时，你会将所有静态文件收集到一个文件夹中，然后由专用的静态文件服务器提供服务。static/hello 子文件夹确保当收集应用的静态文件时，它们位于特定于应用的子文件夹中，并且不会与同一项目中其他应用的文件冲突。
在 static/hello 文件夹中，创建一个名为 site.css 的文件，内容如下。输入此代码后，还可以观察 VS Code 为 CSS 文件提供的语法突出显示，包括颜色预览。
```
.message {
    font-weight: 600;
    color: blue;
}
```
在 templates/hello/hello_there.html 中，在 <title> 元素后添加以下行。{% load static %} 标记是一个自定义 Django 模板标记集，它允许你使用 {% static %} 来引用文件，例如样式表。
```
{% load static %}
<link rel="stylesheet" type="text/css" href="{% static 'hello/site.css' %}" />
```
同样在 templates/hello/hello_there.html 中，将 <body> 元素的内容替换为以下标记，该标记使用 message 样式而不是 <strong> 标记
```
<span class="message">Hello, there {{ name }}!</span> It's {{ date | date:'l, d F, Y' }} at {{ date | time:'H:i:s' }}.
```
运行应用，导航到 /hello/name URL，并观察消息以蓝色呈现。完成后停止应用。

使用 collectstatic 命令

对于生产部署，你通常使用 python manage.py collectstatic 命令将所有静态文件从你的应用收集到一个文件夹中。然后，你可以使用专用的静态文件服务器来提供这些文件，这通常会带来更好的整体性能。以下步骤展示了如何进行此收集，尽管在使用 Django 开发服务器运行时你不会使用此收集。

在 web_project/settings.py 中，添加以下行，定义在使用 collectstatic 命令时收集静态文件的位置
```
STATIC_ROOT = BASE_DIR / 'static_collected'
```
在终端中，运行命令 python manage.py collectstatic 并观察到 hello/site.css 被复制到顶层 static_collected 文件夹中，与 manage.py 并排。
在实践中，每次更改静态文件以及部署到生产环境之前，都要运行 collectstatic。

创建扩展基本模板的多个模板

由于大多数 Web 应用都有多个页面，并且由于这些页面通常共享许多通用元素，因此开发者将这些通用元素分离到基页模板中，然后其他页面模板扩展该基页模板。（这也称为模板继承，意味着扩展页面从基页继承元素。）

此外，由于你可能会创建许多扩展同一模板的页面，因此在 VS Code 中创建一个代码片段会很有帮助，你可以使用该代码片段快速初始化新的页面模板。代码片段可帮助你避免繁琐且容易出错的复制粘贴操作。

以下各节将逐步介绍此过程的不同部分。

创建基页模板和样式

Django 中的基页模板包含一组页面的所有共享部分，包括对 CSS 文件、脚本文件等的引用。基模板还定义一个或多个块标记，扩展模板应覆盖其内容。块标记在基模板和扩展模板中都用 {% block <name> %} 和 {% endblock %} 划定。

以下步骤演示如何创建基模板。

在 templates/hello 文件夹中，创建一个名为 layout.html 的文件，内容如下，其中包含名为“title”和“content”的块。正如你所看到的，标记定义了一个简单的导航栏结构，其中包含指向主页、关于和联系页面的链接，你将在后面的章节中创建这些页面。请注意使用 Django 的 {% url %} 标记通过相应 URL 模式的名称而不是相对路径来引用其他页面。

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8"/>
    <title>{% block title %}{% endblock %}</title>
    {% load static %}
    <link rel="stylesheet" type="text/css" href="{% static 'hello/site.css' %}"/>
</head>

<body>
<div class="navbar">
    <a href="{% url 'home' %}" class="navbar-brand">Home</a>
    <a href="{% url 'about' %}" class="navbar-item">About</a>
    <a href="{% url 'contact' %}" class="navbar-item">Contact</a>
</div>

<div class="body-content">
    {% block content %}
    {% endblock %}
    <hr/>
    <footer>
        <p>&copy; 2018</p>
    </footer>
</div>
</body>
</html>

将以下样式添加到 static/hello/site.css 中现有“message”样式的下方，并保存文件。（本演练不尝试演示响应式设计；这些样式只是生成了一个相当有趣的结果。）

.navbar {
    background-color: lightslategray;
    font-size: 1em;
    font-family: 'Trebuchet MS', 'Lucida Sans Unicode', 'Lucida Grande', 'Lucida Sans', Arial, sans-serif;
    color: white;
    padding: 8px 5px 8px 5px;
}

.navbar a {
    text-decoration: none;
    color: inherit;
}

.navbar-brand {
    font-size: 1.2em;
    font-weight: 600;
}

.navbar-item {
    font-variant: small-caps;
    margin-left: 30px;
}

.body-content {
    padding: 5px;
    font-family:'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
}

你可以在此时运行应用，但由于你尚未在任何地方使用基模板，并且尚未更改任何代码文件，因此结果与上一步相同。完成其余部分以查看最终效果。

创建代码片段

由于你在下一节中创建的三个页面扩展了 layout.html，因此创建代码片段以使用对基模板的适当引用来初始化新模板文件可以节省时间。代码片段从单个来源提供一致的代码片段，从而避免了在使用从现有代码复制粘贴时可能出现的错误。

在 VS Code 中，选择文件（Windows/Linux）或 Code (macOS) 菜单，然后选择首选项 > 用户代码片段。
在出现的列表中，选择 html。（如果之前创建过代码片段，则该选项可能会在列表的现有代码片段部分中显示为“html.json”。）

在 VS Code 打开 html.json 后，在现有花括号内添加以下代码。（此处未显示的解释性注释描述了诸如 $0 行如何指示 VS Code 在插入代码片段后放置光标的位置等详细信息）

"Django Tutorial: template extending layout.html": {
    "prefix": "djextlayout",
    "body": [
        "{% extends \"hello/layout.html\" %}",
        "{% block title %}",
        "$0",
        "{% endblock %}",
        "{% block content %}",
        "{% endblock %}"
    ],

    "description": "Boilerplate template that extends layout.html"
},

保存 html.json 文件 (⌘S (Windows, Linux Ctrl+S))。
现在，每当你开始键入代码片段的前缀（例如 djext）时，VS Code 都会将该代码片段作为自动完成选项提供，如下一节所示。你还可以使用插入代码片段命令从菜单中选择代码片段。

有关代码片段的更多信息，请参阅创建代码片段。

使用代码片段添加页面

有了代码片段，你可以快速创建主页、关于和联系页面的模板。

在 templates/hello 文件夹中，创建一个名为 home.html 的新文件，然后开始键入 djext 以查看代码片段作为完成项出现

当你选择完成项时，代码片段的代码会出现在代码片段的插入点处，光标位于该位置
在“title”块中的插入点，写入 Home，在“content”块中，写入 <p>Home page for the Visual Studio Code Django tutorial.</p>，然后保存文件。这些行是扩展页面模板的唯一部分
在 templates/hello 文件夹中，创建 about.html，使用代码片段插入样板标记，在“title”和“content”块中分别插入 About us 和 <p>About page for the Visual Studio Code Django tutorial.</p>，然后保存文件。
重复上一步以创建 templates/hello/contact.html，分别使用 Contact us 和 <p>Contact page for the Visual Studio Code Django tutorial.</p>。
在应用的 urls.py 中，为 /about 和 /contact 页面添加路由。请注意，path 函数的 name 参数定义了你在模板中的 {% url %} 标记中引用页面的名称。
```
path("about/", views.about, name="about"),
path("contact/", views.contact, name="contact"),
```

在 views.py 中，为 /about 和 /contact 路由添加函数，这些函数引用它们各自的页面模板。还要修改 home 函数以使用 home.html 模板。

# Replace the existing home function with the one below
def home(request):
    return render(request, "hello/home.html")

def about(request):
    return render(request, "hello/about.html")

def contact(request):
    return render(request, "hello/contact.html")

运行应用

有了所有页面模板，保存 views.py，运行应用，然后打开浏览器访问主页以查看结果。在页面之间导航以验证页面模板是否正确扩展了基模板。

Django tutorial: app rendering a common nav bar from the base template

使用数据、数据模型和迁移

许多 Web 应用使用存储在数据库中的信息，Django 使使用模型表示该数据库中的对象变得容易。在 Django 中，模型是一个 Python 类，派生自 django.db.models.Model，它表示特定的数据库对象，通常是一个表。你将这些类放在应用的 models.py 文件中。

使用 Django，你几乎完全通过在代码中定义的模型来操作数据库。然后，Django 的“迁移”会自动处理底层数据库的所有细节，因为你会随着时间的推移发展模型。一般工作流程如下

在 models.py 文件中更改模型。
运行 python manage.py makemigrations 以在 migrations 文件夹中生成脚本，这些脚本将数据库从当前状态迁移到新状态。
运行 python manage.py migrate 以将脚本应用于实际数据库。

迁移脚本有效地记录了你随着时间推移对数据模型所做的所有增量更改。通过应用迁移，Django 会更新数据库以匹配你的模型。由于每个增量更改都有自己的脚本，因此 Django 可以自动将任何先前版本的数据库（包括新数据库）迁移到当前版本。因此，你只需要关注 models.py 中的模型，而无需关注底层数据库架构或迁移脚本。让 Django 完成那部分！

在代码中，你也完全使用模型类来存储和检索数据；Django 处理底层细节。唯一的例外是你可以使用 Django 管理实用程序 loaddata 命令将数据写入数据库。此实用程序通常用于在 migrate 命令初始化架构后初始化数据集。

当使用 db.sqlite3 文件时，你还可以使用像 SQLite 浏览器这样的工具直接操作数据库。使用此类工具在表中添加或删除记录是可以的，但要避免更改数据库架构，因为数据库将与应用的模型不同步。相反，更改模型，运行 makemigrations，然后运行 migrate。

数据库类型

默认情况下，Django 包含一个 db.sqlite3 文件作为应用的数据库，该文件适用于开发工作。正如何时使用 SQLite (sqlite.org) 上所述，SQLite 适用于每天点击量少于 10 万次的低到中等流量站点，但不建议用于更高流量的站点。它也仅限于单台计算机，因此不能用于任何多服务器场景，例如负载平衡和地理复制。

由于这些原因，请考虑使用生产级数据存储，例如 PostgreSQL、MySQL 和 SQL Server。有关 Django 对其他数据库的支持的信息，请参阅数据库设置。你还可以使用 Azure Python SDK 来处理 Azure 存储服务，如表和 Blob。

定义模型

Django 模型再次是一个 Python 类，派生自 django.db.model.Models，你将其放在应用的 models.py 文件中。在数据库中，每个模型都会自动获得一个名为 id 的唯一 ID 字段。所有其他字段都定义为类的属性，使用来自 django.db.models 的类型，例如 CharField（有限文本）、TextField（无限文本）、EmailField、URLField、IntegerField、DecimalField、BooleanField、DateTimeField、ForeignKey 和 ManyToMany 等。（有关详细信息，请参阅 Django 文档中的模型字段参考。）

每个字段都带有一些属性，例如 max_length。blank=True 属性表示该字段是可选的；null=true 表示值是可选的。还有一个 choices 属性，它将值限制为数据值/显示值元组数组中的值。

例如，在 models.py 中添加以下类，以定义一个数据模型，该模型表示简单消息日志中的日期条目

from django.db import models
from django.utils import timezone

class LogMessage(models.Model):
    message = models.CharField(max_length=300)
    log_date = models.DateTimeField("date logged")

    def __str__(self):
        """Returns a string representation of a message."""
        date = timezone.localtime(self.log_date)
        return f"'{self.message}' logged on {date.strftime('%A, %d %B, %Y at %X')}"

模型类可以包含返回从其他类属性计算的值的方法。模型通常包括一个 __str__ 方法，该方法返回实例的字符串表示形式。

迁移数据库

由于你通过编辑 models.py 更改了数据模型，因此你需要更新数据库本身。在 VS Code 中，打开一个激活了虚拟环境的终端（使用终端：创建新终端命令，⌃⇧` (Windows, Linux Ctrl+Shift+`)），导航到项目文件夹，然后运行以下命令

python manage.py makemigrations
python manage.py migrate

查看 migrations 文件夹，了解 makemigrations 生成的脚本。你还可以查看数据库本身，以了解架构已更新。

如果在运行命令时看到错误，请确保你没有使用从先前步骤遗留下来的调试终端，因为它们可能未激活虚拟环境。

通过模型使用数据库

有了模型并迁移了数据库，你就可以仅使用模型来存储和检索数据。在本节中，你将向应用添加一个表单页面，你可以通过该页面记录消息。然后，你将修改主页以显示这些消息。由于你在此处修改了许多代码文件，因此请注意细节。

在 hello 文件夹（你有 views.py 的位置）中，创建一个名为 forms.py 的新文件，其中包含以下代码，该代码定义了一个 Django 表单，其中包含从数据模型 LogMessage 中提取的字段

from django import forms
from hello.models import LogMessage

class LogMessageForm(forms.ModelForm):
    class Meta:
        model = LogMessage
        fields = ("message",)   # NOTE: the trailing comma is required

在 templates/hello 文件夹中，创建一个名为 log_message.html 的新模板，内容如下，该模板假定模板被赋予一个名为 form 的变量来定义表单的主体。然后，它添加一个带有标签“Log”的提交按钮。
```
{% extends "hello/layout.html" %}
{% block title %}
    Log a message
{% endblock %}
{% block content %}
    <form method="POST" class="log-form">
        {% csrf_token %}
        {{ form.as_p }}
        <button type="submit" class="save btn btn-default">Log</button>
    </form>
{% endblock %}
```
注意：Django 的 {% csrf_token %} 标记提供针对跨站请求伪造的保护。有关详细信息，请参阅 Django 文档中的跨站请求伪造保护。
在应用的 static/hello/site.css 文件中，添加一个规则以使输入表单更宽
```
input[name=message] {
    width: 80%;
}
```
在应用的 urls.py 文件中，为新页面添加路由
```
path("log/", views.log_message, name="log"),
```

在 views.py 中，定义名为 log_message 的视图（如 URL 路由所引用）。此视图处理 HTTP GET 和 POST 案例。在 GET 案例（else: 部分）中，它只显示你在先前步骤中定义的表单。在 POST 案例中，它从表单中检索数据到数据对象 (message)，设置时间戳，然后保存该对象，此时它将被写入数据库

# Add these to existing imports at the top of the file:
from django.shortcuts import redirect
from hello.forms import LogMessageForm
from hello.models import LogMessage

# Add this code elsewhere in the file:
def log_message(request):
    form = LogMessageForm(request.POST or None)

    if request.method == "POST":
        if form.is_valid():
            message = form.save(commit=False)
            message.log_date = datetime.now()
            message.save()
            return redirect("home")
    else:
        return render(request, "hello/log_message.html", {"form": form})

在你可以尝试所有操作之前，还需要一步！在 templates/hello/layout.html 中，在“navbar”div 中为消息日志记录页面添加链接
```

<a href="{% url 'log' %}" class="navbar-item">Log Message</a>
```
运行应用并打开浏览器访问主页。选择导航栏上的记录消息链接，该链接应显示消息日志记录页面
输入消息，选择记录，你应该被带回主页。主页尚未显示任何已记录的消息（你稍后会解决这个问题）。随意记录更多消息。如果需要，可以使用像 SQLite Browser 这样的工具查看数据库，以了解是否已创建记录。以只读方式打开数据库，否则请记住在使用应用之前关闭数据库，否则应用将因数据库被锁定而失败。
完成后停止应用。

现在修改主页以显示已记录的消息。首先将应用的 templates/hello/home.html 文件的内容替换为以下标记。此模板需要一个名为 message_list 的上下文变量。如果它接收到一个（使用 {% if message_list %} 标记检查），它将迭代该列表（{% for message in message_list %} 标记）以为每条消息生成表行。否则，页面会指示尚未记录任何消息。

{% extends "hello/layout.html" %}
{% block title %}
    Home
{% endblock %}
{% block content %}
    <h2>Logged messages</h2>

    {% if message_list %}
        <table class="message_list">
            <thead>
            <tr>
                <th>Date</th>
                <th>Time</th>
                <th>Message</th>
            </tr>
            </thead>
            <tbody>
            {% for message in message_list %}
                <tr>
                    <td>{{ message.log_date | date:'d M Y' }}</td>
                    <td>{{ message.log_date | time:'H:i:s' }}</td>
                    <td>
                        {{ message.message }}
                    </td>
                </tr>
            {% endfor %}
            </tbody>
        </table>
    {% else %}
        <p>No messages have been logged. Use the <a href="{% url 'log' %}">Log Message form</a>.</p>
    {% endif %}
{% endblock %}

在 static/hello/site.css 中，添加一个规则以稍微格式化表格

.message_list th,td {
    text-align: left;
    padding-right: 15px;
}

在 views.py 中，导入 Django 的通用 ListView 类，我们将使用它来实现主页
```
from django.views.generic import ListView
```

同样在 views.py 中，将 home 函数替换为名为 HomeListView 的类，该类派生自 ListView，它将自身绑定到 LogMessage 模型并实现一个函数 get_context_data 以生成模板的上下文。

# Remove the old home function if you want; it's no longer used

class HomeListView(ListView):
    """Renders the home page, with a list of all messages."""
    model = LogMessage

    def get_context_data(self, **kwargs):
        context = super(HomeListView, self).get_context_data(**kwargs)
        return context

在应用的 urls.py 中，导入数据模型
```
from hello.models import LogMessage
```

同样在 urls.py 中，为新视图创建一个变量，该变量按降序检索五个最新的 LogMessage 对象（这意味着它查询数据库），然后在模板上下文中为数据提供名称 (message_list)，并标识要使用的模板

home_list_view = views.HomeListView.as_view(
    queryset=LogMessage.objects.order_by("-log_date")[:5],  # :5 limits the results to the five most recent
    context_object_name="message_list",
    template_name="hello/home.html",
)

在 urls.py 中，修改主页的路径以使用 home_list_view 变量

    # Replace the existing path for ""
    path("", home_list_view, name="home"),

启动应用并打开浏览器访问主页，现在应该显示消息
完成后停止应用。

将调试器与页面模板结合使用

如上一节所示，页面模板可以包含过程指令，如 {% for message in message_list %} 和 {% if message_list %}，而不仅仅是被动的声明性元素，如 {% url %} 和 {% block %}。因此，你可以在模板内部像在任何其他过程代码中一样遇到编程错误。

幸运的是，当调试配置中具有 "django": true 时（你已经这样做），VS Code 的 Python 扩展提供了模板调试。以下步骤演示了此功能

在 templates/hello/home.html 中，在 {% if message_list %} 和 {% for message in message_list %} 行上都设置断点，如下图中的黄色箭头所示
在调试器中运行应用并打开浏览器访问主页。（如果你已经在运行调试器，则不必在设置断点后重新启动应用；只需刷新页面。）观察到 VS Code 在 {% if %} 语句的模板中中断到调试器，并在变量窗格中显示所有上下文变量
使用单步跳过 (F10) 命令单步执行模板代码。观察到调试器单步跳过所有声明性语句，并在任何过程代码处暂停。例如，单步执行 {% for message in message_list %} 循环使你可以检查 message 中的每个值，并使你可以单步执行到诸如 <td>{{ message.log_date | date:'d M Y' }}</td> 之类的行。
你还可以在 调试控制台 面板中使用变量。（但是，控制台中目前不提供 Django 过滤器，如 date。）
准备就绪后，选择继续 (F5) 以完成运行应用并在浏览器中查看渲染的页面。完成后停止调试器。

可选活动

以下各节描述了你可能会在 Python 和 Visual Studio Code 工作中发现有帮助的其他步骤。

为环境创建 requirements.txt 文件

当你通过源代码管理或其他方式共享应用代码时，复制虚拟环境中的所有文件没有意义，因为接收者始终可以自己重新创建该环境。

因此，开发者通常会从源代码管理中省略虚拟环境文件夹，而是使用 requirements.txt 文件描述应用的依赖项。

尽管你可以手动创建文件，但你也可以使用 pip freeze 命令基于激活环境中安装的确切库生成文件

使用 Python: 选择解释器 命令选择你选择的环境后，运行 终端：创建新终端 命令 (⌃⇧` (Windows, Linux Ctrl+Shift+`))) 以打开一个激活了该环境的终端。
在终端中，运行 pip freeze > requirements.txt 以在项目文件夹中创建 requirements.txt 文件。

接收项目副本的任何人（或任何生成服务器）只需要运行 pip install -r requirements.txt 命令即可在活动环境中重新安装应用所依赖的包。

注意：pip freeze 列出了你在当前环境中安装的所有 Python 包，包括你当前未使用的包。该命令还列出了具有确切版本号的包，你可能希望将这些包转换为范围，以便将来具有更大的灵活性。有关更多信息，请参阅 pip 命令文档中的Requirements Files。

创建超级用户并启用管理界面

默认情况下，Django 为 Web 应用提供了一个受身份验证保护的管理界面。该界面通过内置的 django.contrib.admin 应用实现，该应用默认包含在项目的 INSTALLED_APPS 列表 (settings.py) 中，身份验证由内置的 django.contrib.auth 应用处理，该应用也默认在 INSTALLED_APPS 中。

执行以下步骤以启用管理界面

通过在 VS Code 中为你的虚拟环境打开终端，然后运行命令 python manage.py createsuperuser --username=<username> --email=<email> 在应用中创建超级用户帐户，当然，将 <username> 和 <email> 替换为你的个人信息。当你运行该命令时，Django 会提示你输入并确认密码。

请务必记住你的用户名和密码组合。这些是你用于向应用进行身份验证的凭据。
在项目级 urls.py (本教程中的 web_project/urls.py) 中添加以下 URL 路由，以指向内置的管理界面
```
# This path is included by default when creating the app
 path("admin/", admin.site.urls),
```
运行服务器，然后打开浏览器访问应用的 /admin 页面（例如，使用开发服务器时为 http://127.0.0.1:8000/admin）。
将出现一个登录页面，由 django.contrib.auth 提供。输入你的超级用户凭据。
通过身份验证后，你将看到默认的管理页面，你可以通过该页面管理用户和组

你可以根据需要自定义管理界面。例如，你可以提供编辑和删除数据库中条目的功能。有关进行自定义的更多信息，请参阅Django 管理站点文档。

使用 Docker 扩展为 Django 应用创建容器

Docker 扩展使从 Visual Studio Code 构建、管理和部署容器化应用程序变得容易。如果你有兴趣了解如何为本教程中开发的 Django 应用创建 Python 容器，请查看容器中的 Python 教程，该教程将引导你完成以下操作

创建一个 Dockerfile 文件，描述简单的 Python 容器。
构建、运行和验证 Django 应用的功能。
调试在容器中运行的应用。

后续步骤

恭喜你完成本 Visual Studio Code 中使用 Django 的演练！

本教程的完整代码项目可以在 GitHub 上找到：python-sample-vscode-django-tutorial。

在本教程中，我们只介绍了 Django 功能的冰山一角。请务必访问 Django 文档和官方 Django 教程，以获取有关视图、模板、数据模型、URL 路由、管理界面、使用其他类型的数据库、部署到生产环境等更多详细信息。

若要在生产网站上试用你的应用，请查看教程 Deploy Python apps to Azure App Service using Docker Containers。Azure 还提供了一个标准容器，App Service on Linux，你可以从中在 VS Code 内部署 Web 应用。

你可能还需要查看 VS Code 文档中与 Python 相关的以下文章

02/06/2025