Django 入门实战：从环境搭建到构建你的第一个 Web 应用

恭喜你选择 Django 作为你学习 Python Web 开发的起点！Django 是一个强大、成熟且功能齐全的框架，非常适合构建中大型的 Web 应用程序。本篇将通过一个简单的例子，带你走完 Django 开发的核心流程。

我们将构建一个非常简单的应用：一个显示项目列表的页面，这些项目数据存储在数据库中，并且可以通过 Django 自带的管理后台进行管理。

我们将要完成的步骤：

搭建开发环境 (Python, pip, 虚拟环境, Django)。
创建一个 Django 项目。
创建一个 Django 应用。
定义一个简单的视图 (View)。
配置 URL 路由 (URL Dispatcher)。
使用模板 (Template) 渲染 HTML。
定义模型 (Model)，与数据库交互。
使用 Django 自带的管理后台管理数据。
在页面上显示数据库中的数据。

开始吧！

Part 1: 环境搭建

首先，确保你的电脑已经安装了 Python 和 pip。建议使用 Python 3.7 或更高版本。

创建和激活虚拟环境：

使用虚拟环境是 Python 开发的最佳实践，它可以隔离不同项目之间的依赖，避免冲突。

打开命令提示符 (Command Prompt) 或 PowerShell。
- 创建一个新的虚拟环境（例如命名为 myproject_venv）：
  Bash
```
python -m venv myproject_venv
```
  这会在当前目录下创建一个名为 myproject_venv 的文件夹。
- 激活虚拟环境：
  - Windows 命令提示符 (Command Prompt): Bash
```
myproject_venv\Scripts\activate.bat
```
  - Windows PowerShell: PowerShell
```
myproject_venv\Scripts\Activate.ps1
```
    如果遇到执行策略问题，可以尝试运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser 并同意。
  激活成功后，你的命令行提示符前面会显示虚拟环境的名称，例如 (myproject_venv) C:\YourProject>。
在虚拟环境中安装 Django：

确保虚拟环境已激活，然后使用 pip 安装 Django。
Bash
```
pip install django
```
等待安装完成。
验证 Django 安装：

可以运行以下命令检查 Django 是否成功安装以及版本号。
Bash
```
django-admin --version
```
如果显示版本号，说明安装成功。

Part 2: 创建一个 Django 项目

Django 项目是整个 Web 应用的容器，包含配置和设置。

在项目目录下创建 Django 项目：

在你的项目目录（例如，你刚刚创建虚拟环境的那个目录）下，运行以下命令：
Bash
```
django-admin startproject myproject .
```
- django-admin 是 Django 的命令行工具。
- startproject 是一个命令，用于创建一个新项目。
- myproject 是你给项目取的名称。
- 后面的 . 表示在当前目录创建项目文件和目录，而不是在当前目录下再创建一个 myproject 子目录。
成功运行后，你的项目目录下会生成以下文件和目录结构：
```
.
├── manage.py
└── myproject
    ├── __init__.py
    ├── asgi.py
    ├── settings.py
    ├── urls.py
    └── wsgi.py
```
- manage.py: 一个命令行工具，用于与项目进行各种交互，如运行服务器、执行数据库迁移等。
- myproject/: 项目的配置目录。
  - settings.py: 项目的主要配置文件。
  - urls.py: 项目的 URL 路由配置文件。
  - wsgi.py, asgi.py: 用于部署的服务器入口文件。
运行开发服务器：

进入包含 manage.py 文件的项目根目录，运行以下命令：
Bash
```
python manage.py runserver
```
服务器会启动，默认运行在 http://127.0.0.1:8000/。

打开你的浏览器，访问 http://127.0.0.1:8000/。如果看到一个带有火箭图标的“The install worked successfully! Congratulations!”页面，说明你的 Django 项目已经成功创建并运行起来了！

在命令行窗口中，按下 Ctrl + C 可以停止开发服务器。

Part 3: 创建一个应用 (App)

Django 鼓励将项目功能拆分成独立、可复用的“应用”(App)。每个 App 通常负责一个特定的功能模块。

在项目根目录下创建应用：

确保你仍在包含 manage.py 的项目根目录下，运行以下命令：

Bash

python manage.py startapp myapp

startapp 是用于创建一个新应用的命令。
myapp 是你给应用取的名称。

成功运行后，你的项目目录下会新增一个 myapp 目录：

.
├── manage.py
├── myenv         # 你的虚拟环境目录
├── myproject     # 项目配置目录
└── myapp         # 新增的应用目录
    ├── migrations    # 数据库迁移文件目录
    ├── __init__.py
    ├── admin.py      # 应用的管理后台配置
    ├── apps.py       # 应用的配置
    ├── models.py     # 应用的模型定义
    ├── tests.py      # 应用的测试
    └── views.py      # 应用的视图定义

将应用添加到项目设置：

新创建的应用需要添加到项目的配置文件 settings.py 中，让 Django 知道这个应用的存在。

打开 myproject/settings.py 文件。
找到 INSTALLED_APPS 列表。
在列表中添加你的应用名称 'myapp'。

Python

# myproject/settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'myapp', # <--- 在这里添加你的应用名称
]

# ... 文件其他内容

Part 4: 定义第一个视图 (View)

视图负责接收 Web 请求并返回响应。我们先创建一个简单的视图，只返回一段文本。

打开应用的 views.py 文件： myapp/views.py。

编写一个简单的函数式视图 (FBV)：

Python

# myapp/views.py

from django.http import HttpResponse # 需要导入 HttpResponse 类

def index(request):
    # 这个函数接收一个 HttpRequest 对象作为参数 (命名为 request 是约定)
    # 它返回一个 HttpResponse 对象，其中包含了要发送给浏览器的文本内容
    return HttpResponse("Hello, Django!")

Part 5: 配置 URL 路由 (URL Routing)

我们需要告诉 Django，当用户访问某个特定的 URL 时，应该由哪个视图来处理。这通过配置 URL 路由实现。通常，一个应用有自己的 urls.py 文件，然后项目的根 urls.py 包含应用的 URL。

在应用目录中创建 urls.py 文件：

在 myapp 目录下创建一个新的 Python 文件 urls.py。

编辑应用的 urls.py：

定义一个 urlpatterns 列表，其中包含 URL 模式与视图函数的对应关系。

Python

# myapp/urls.py

from django.urls import path # 需要导入 path 函数
from . import views # 从当前应用目录导入 views.py

# urlpatterns 是一个列表，定义了 URL 模式
urlpatterns = [
    # path(route, view, name=None)
    # route: 匹配的 URL 路径 (这里是空字符串 '', 表示匹配应用 URL 的根路径)
    # view: 处理该请求的视图函数 (views.index)
    # name: 给这个 URL 起一个名字，方便在模板或代码中引用 (可选但推荐)
    path('', views.index, name='index'),
    # 你可以在这里添加更多 path() 来定义其他 URL
    # path('about/', views.about, name='about'),
]

编辑项目的根 urls.py：

打开 myproject/urls.py 文件，包含 myapp 应用的 URL 配置。

Python

# myproject/urls.py

from django.contrib import admin
from django.urls import path, include # 需要导入 include 函数

urlpatterns = [
    # 这是 Django 内置管理后台的 URL
    path('admin/', admin.site.urls),

    # 使用 include() 将 myapp 应用的 URL 配置包含进来
    # 当用户访问以 'myapp/' 开头的 URL 时，Django 会将剩余的 URL 部分传递给 myapp.urls 去处理
    path('myapp/', include('myapp.urls')),

    # 你也可以直接在项目根 urls.py 中定义简单的 URL 模式
    # path('', views.home, name='home'), # 如果你的 home 视图在项目根目录的 views.py 中
]

测试第一个视图和 URL：

确保你在项目根目录（manage.py 所在目录），运行开发服务器：
Bash
```
python manage.py runserver
```
打开浏览器，访问 http://127.0.0.1:8000/myapp/。你应该能看到页面上显示“Hello, Django!”。这表明你成功地将一个 URL 映射到了一个视图，并返回了响应。

Part 6: 使用模板 (Template)

直接在视图中返回 HTML 字符串不适合复杂的页面。Django 使用模板来分离视图逻辑和页面展示。

创建模板目录和模板文件：

按照 Django 的约定，模板文件通常放在应用的 templates 目录下的一个与应用同名的子目录中。
- 在 myapp 目录下创建 templates 目录：myapp/templates/。
- 在 templates 目录下创建 myapp 子目录：myapp/templates/myapp/。
- 在 myapp/templates/myapp/ 目录下创建一个新的 HTML 文件，例如 index.html。

编辑模板文件 (myapp/templates/myapp/index.html)：

编写一些 HTML 代码，并使用 Django 模板语言 (DTL) 显示一个变量。

HTML

<!DOCTYPE html>
<html>
<head>
    <title>我的第一个 Django 模板</title>
</head>
<body>
    {# 这是一个模板注释 #}
    <h1>{{ greeting }}</h1> {# 使用 {{ 变量名 }} 显示从视图传递的变量 #}
    <p>这是一个使用模板渲染的页面。</p>
</body>
</html>

修改视图以使用模板：

修改 myapp/views.py 中的 index 视图，使用 render() 快捷函数来加载和渲染模板。render() 函数会自动查找 templates 目录。

Python

# myapp/views.py

# from django.http import HttpResponse # 不再直接返回 HttpResponse
from django.shortcuts import render # 需要导入 render 函数

def index(request):
    # 准备传递给模板的数据 (上下文)
    context = {
        'greeting': 'Hello from Template Context!', # 定义一个变量 'greeting'
        'other_variable': '...' # 可以传递更多变量
    }

    # 使用 render 函数加载并渲染模板
    # render(request, template_name, context=None)
    # request: HttpRequest 对象
    # template_name: 模板文件相对于某个 templates 目录的路径 (如 'myapp/index.html')
    # context: 传递给模板的数据字典
    return render(request, 'myapp/index.html', context)

测试使用模板的视图：

确保服务器正在运行，再次访问 http://127.0.0.1:8000/myapp/。你应该能看到一个标准的 HTML 页面，其中 H1 标题显示着“Hello from Template Context!”。这表明你成功地将数据从视图传递到了模板并进行了渲染。

Part 7: 使用模型 (Model) 与数据库

Django 的 ORM 让你用 Python 类定义数据结构，然后自动映射到数据库。

数据库设置：

Django 默认使用 SQLite 数据库，配置在 settings.py 的 DATABASES 字典中。对于入门而言，默认设置即可，无需安装额外数据库软件。

定义第一个模型：

打开应用的 models.py 文件 (myapp/models.py)，定义一个简单的 Item 模型。

Python

# myapp/models.py

from django.db import models # 需要导入 models 模块

class Item(models.Model): # 继承自 models.Model
    # 定义模型字段，对应数据库表的列
    name = models.CharField(max_length=100) # 字符串字段，最大长度 100
    created_at = models.DateTimeField(auto_now_add=True) # 日期时间字段，创建时自动设置当前时间

    # __str__ 方法定义了模型对象在被打印或在管理后台显示时的字符串表示
    def __str__(self):
        return self.name

    # 你可以在这里定义其他字段，如 models.IntegerField(), models.TextField(), models.BooleanField(), models.ForeignKey() 等

创建数据库迁移 (Migrations)：

模型定义完成后，需要告诉 Django 根据模型的变化创建数据库迁移文件。
- 确保你在项目根目录（manage.py 所在目录），并且虚拟环境已激活。
- 运行命令： Bash
```
python manage.py makemigrations myapp # 指定应用名称
```
- Django 会检测到你在 myapp/models.py 中定义了 Item 模型，并在 myapp/migrations/ 目录下生成一个 Python 文件（例如 0001_initial.py），记录了创建 Item 表的步骤。
应用数据库迁移：

生成迁移文件后，需要将其应用到数据库，创建实际的数据库表。
- 确保你在项目根目录，虚拟环境已激活。
- 运行命令： Bash
```
python manage.py migrate
```
- Django 会执行所有未应用的迁移，包括你的应用和 Django 内置应用（如用户认证、管理后台）的迁移，创建所需的数据库表。如果使用 SQLite，你会在项目根目录看到一个 db.sqlite3 文件被创建或更新。

Part 8: 使用 Django 自带的管理后台管理数据

Django 的杀手级功能之一是自动化的管理后台，可以让你方便地查看和管理数据库中的数据。

创建超级用户 (Superuser)：

你需要创建一个超级用户账号来登录管理后台。
- 确保你在项目根目录，虚拟环境已激活。
- 运行命令： Bash
```
python manage.py createsuperuser
```
- 按照提示输入用户名、邮箱（可选）和密码。密码输入时不会显示字符，输完按回车即可。

注册模型到管理后台：

默认情况下，你的自定义模型不会显示在管理后台。你需要显式地注册它们。

打开应用的 admin.py 文件 (myapp/admin.py)。
导入你的模型，并使用 admin.site.register() 函数注册。

Python

# myapp/admin.py

from django.contrib import admin
from .models import Item # 导入你的 Item 模型

# 在管理后台注册 Item 模型
admin.site.register(Item)

# 你也可以在这里注册其他模型
# from .models import AnotherModel
# admin.site.register(AnotherModel)

访问管理后台并添加数据：
- 确保开发服务器正在运行 (python manage.py runserver)。
- 打开浏览器，访问 http://127.0.0.1:8000/admin/。
- 使用你刚刚创建的超级用户账号登录。
- 登录成功后，你应该能在侧边栏看到你的应用名称（myapp）以及下面的 Items。
- 点击 Items，然后点击右上角的“添加 Item”按钮。
- 输入一些 Item 数据（只需要输入 Name 字段，created_at 会自动生成），点击“保存”。添加几个 Item。

Part 9: 在页面上显示数据库中的数据

现在，我们回到前面创建的页面，修改视图和模板，从数据库中获取 Item 数据并显示出来。

修改视图，从数据库获取数据：

打开 myapp/views.py 文件，修改 index 视图，使用 ORM 查询 Item 模型的数据。

Python

# myapp/views.py

from django.shortcuts import render
from .models import Item # 需要导入你的 Item 模型类

def index(request):
    # 使用 ORM 从数据库获取所有的 Item 对象
    # Item.objects 是一个管理器，提供数据库查询接口
    # .all() 方法获取所有的 Item 对象，返回一个 QuerySet (类似列表)
    items_list = Item.objects.all()

    # 准备传递给模板的数据
    context = {
        'greeting': '我的项目列表',
        'items': items_list # 将获取到的 Item 列表传递给模板，变量名为 'items'
    }

    # 渲染模板
    return render(request, 'myapp/index.html', context)

修改模板，显示获取到的数据：

打开 myapp/templates/myapp/index.html 文件，使用 Django 模板语言循环遍历 items 列表并显示每个 Item 的信息。

HTML

<!DOCTYPE html>
<html>
<head>
    <title>我的项目列表</title>
</head>
<body>
    <h1>{{ greeting }}</h1>

    <h2>项目列表：</h2>
    {% if items %} {# 检查 items 列表是否存在且非空 #}
        <ul>
        {% for item in items %} {# 模板标签：循环遍历 items 列表，每次循环将当前元素赋给 item #}
            <li>
                {# 显示当前 item 对象的属性 #}
                {{ item.name }} (创建时间: {{ item.created_at }})
            </li>
        {% endfor %}
        </ul>
    {% else %}
        {# 如果 items 列表为空，显示此段落 #}
        <p>目前还没有项目数据。</p>
    {% endif %}

</body>
</html>