Django 是我接触的第一个“全家桶”式 Web 框架。它把路由、模板、ORM、后台管理都内置好了, 对新手来说最大的好处是:不用先纠结选型,按官方约定就能跑起来。 这篇文章记录从零到一个可访问页面的完整过程。

1. 准备环境

先按上一篇的方法创建虚拟环境,然后安装 Django。建议限定主版本范围,避免教程和实际代码对不上:

python -m venv .venv
.venv\Scripts\Activate.ps1          # macOS/Linux 用 source .venv/bin/activate
python -m pip install "Django>=5.0,<6.0"
python -m django --version

看到版本号输出,说明安装成功。

2. 创建项目

Django 用 django-admin 管理项目骨架。startproject 会生成一个项目目录:

django-admin startproject mysite .
python manage.py runserver

末尾的 . 表示把项目文件生成在当前目录,而不是再套一层 mysite/。 这是一个很实用的小技巧,能让目录结构更扁平:

.
├── manage.py
└── mysite
    ├── __init__.py
    ├── asgi.py
    ├── settings.py
    ├── urls.py
    └── wsgi.py

打开 http://127.0.0.1:8000,应该能看到 Django 的欢迎页(一个小火箭)。 这说明开发服务器已经跑通了。

各文件的作用

文件说明
manage.py命令行入口,迁移、创建应用、启动服务都靠它
settings.py全局配置:数据库、应用列表、模板、中间件等
urls.py根路由表,把 URL 映射到视图
wsgi.py / asgi.py部署时交给 Web 服务器或 ASGI 容器的入口

3. 创建一个应用

在 Django 里,“项目”是站点整体,“应用”是功能模块。一个项目可以包含多个应用, 比如 blog、accounts、api。先把博客应用建出来:

python manage.py startapp blog

得到这样的结构:

blog
├── __init__.py
├── admin.py
├── apps.py
├── migrations
│   └── __init__.py
├── models.py
├── tests.py
└── views.py

然后把应用注册到 settings.py 的 INSTALLED_APPS 中, 否则模型和模板都不会被 Django 识别:

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "blog",          # 新加这一行
]

4. 写第一个视图

Django 的请求流程是经典的 MTV:URL 找到 View,View 取数据后交给 Template 渲染。 先写一个最简单的视图,直接返回 HTML:

# blog/views.py
from django.http import HttpResponse


def index(request):
    return HttpResponse("<h1>Hello, Django</h1>")

接着在应用内新建 blog/urls.py:

# blog/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path("", views.index, name="blog-index"),
]

再把它挂到项目根路由上:

# mysite/urls.py
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("admin/", admin.site.urls),
    path("blog/", include("blog.urls")),
]

访问 http://127.0.0.1:8000/blog/,就能看到那句 Hello。 这种“应用自带路由表、项目统一 include”的组织方式,能让每个模块保持独立, 后面拆分服务时也方便迁移。

5. 用模板渲染页面

直接在视图里拼 HTML 不利于维护。Django 的模板系统支持变量、循环、继承。 先在应用下建模板目录:blog/templates/blog/index.html。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>{{ title }}</title>
</head>
<body>
  <h1>{{ title }}</h1>
  <ul>
    {% for post in posts %}
      <li>{{ post.title }} — {{ post.created_at|date:"Y-m-d" }}</li>
    {% empty %}
      <li>暂无文章</li>
    {% endfor %}
  </ul>
</body>
</html>

视图改成使用 render:

# blog/views.py
from django.shortcuts import render


def index(request):
    posts = [
        {"title": "第一篇文章", "created_at": None},
        {"title": "第二篇文章", "created_at": None},
    ]
    return render(request, "blog/index.html", {
        "title": "我的博客",
        "posts": posts,
    })

模板里的 {% for %} 和 {{ }} 是 Django 模板语法。 它刻意做得比 Python 简单,不允许写复杂表达式,目的是把逻辑留在视图层。

6. 接入数据库

模板里的数据现在是写死的。真实项目需要模型,Django 自带 SQLite, 开发阶段不用额外配置。把示例数据换成一个模型:

# blog/models.py
from django.db import models


class Post(models.Model):
    title = models.CharField("标题", max_length=120)
    body = models.TextField("正文")
    created_at = models.DateTimeField("创建时间", auto_now_add=True)

    class Meta:
        ordering = ["-created_at"]

    def __str__(self):
        return self.title

生成并执行迁移:

python manage.py makemigrations
python manage.py migrate

makemigrations 根据模型变化生成迁移文件,migrate 把变更同步到数据库。以后每次改模型,都要重复这两步。

视图里就可以直接查询了:

def index(request):
    posts = Post.objects.all()[:10]
    return render(request, "blog/index.html", {"posts": posts})

7. 打开后台管理

Django 自带 admin,只需要创建超级用户并把模型注册进去:

python manage.py createsuperuser
# blog/admin.py
from django.contrib import admin
from .models import Post

admin.site.register(Post)

访问 http://127.0.0.1:8000/admin/,登录后就能可视化地增删文章。 对个人项目来说,这个后台往往已经够用了,不需要再单独开发管理端。

小结

到这里,一个能访问、能存数据、能管理内容的最小 Django 项目就完成了。 接下来值得继续深入的方向有:ORM 查询优化、表单与校验、用户认证, 以及如何用 Gunicorn + Nginx 把它部署到服务器上。

下一篇会专门聊 ORM 里最容易踩的性能坑:N+1 查询。