第一个 Django 应用

本篇接续《初识 Django》，目标是完成一个可运行的第一个应用。

我们将从空项目开始，逐步实现一个最小但完整的“留言列表”应用：

展示所有留言
提交新留言
在 Django 管理后台管理留言

完成后你将真正掌握 Django 的基础开发闭环：url -> view -> model -> template -> form -> admin。

一、前置条件

已安装 Python（建议 3.10+）
会使用命令行
已准备一个项目目录，例如：

cd D:\learn\Python\docs
mkdir Django
cd Django

二、创建虚拟环境并安装 Django

# 创建虚拟环境
python -m venv .venv

# Windows 启用环境
.\venv\Scripts\Activate.ps1

# 安装 Django
pip install django

# 查看版本
python -m django --version

激活命令在 PowerShell 下通常是 \.venv\Scripts\Activate.ps1，如果你的策略不允许执行脚本，先执行：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

三、创建项目与应用

# 创建项目
django-admin startproject mysite
cd mysite

# 创建应用
python manage.py startapp notes

建议先建立目录结构（后面会用到）：

mysite/
  manage.py
  db.sqlite3
  mysite/
    settings.py
    urls.py
    asgi.py
    wsgi.py
  notes/
    models.py
    views.py
    urls.py
    forms.py
    admin.py
    migrations/
    templates/
    static/

四、在 `settings.py` 注册应用

打开 mysite/settings.py，在 INSTALLED_APPS 里加入 notes：

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'notes',
]

五、配置中文友好与时区（可选）

在 settings.py 里可按个人习惯配置：

LANGUAGE_CODE = 'zh-hans'
TIME_ZONE = 'Asia/Shanghai'
USE_TZ = True

六、创建数据库模型（Model）

编辑 notes/models.py：

from django.db import models


class Message(models.Model):
    name = models.CharField(max_length=50)
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return f"{self.name}: {self.content[:20]}"

__str__ 让后台展示更友好，str 用来定义：当一个 Message 对象被转换成字符串时，显示什么内容。。

七、生成迁移并执行

python manage.py makemigrations
python manage.py migrate

如想确认迁移文件已生成，可看：notes/migrations/0001_initial.py

八、创建表单（Form）

编辑 notes/forms.py：

from django import forms
from .models import Message


class MessageForm(forms.ModelForm):
    class Meta:
        model = Message
        fields = ['name', 'content']
        widgets = {
            'content': forms.Textarea(attrs={'rows': 4}),
        }

九、编写视图（View）

编辑 notes/views.py：

from django.shortcuts import redirect, render
from .forms import MessageForm
from .models import Message


def message_list(request):
    messages = Message.objects.all().order_by('-created_at')
    return render(request, 'notes/list.html', {
        'messages': messages,
    })


def message_create(request):
    if request.method == 'POST':
        form = MessageForm(request.POST)
        if form.is_valid():
            form.save()
            return redirect('message_list')
    else:
        form = MessageForm()

    return render(request, 'notes/create.html', {
        'form': form,
    })

十、配置应用路由

创建并编辑 notes/urls.py：

from django.urls import path
from . import views

urlpatterns = [
    path('', views.message_list, name='message_list'),
    path('create/', views.message_create, name='message_create'),
]

编辑 mysite/urls.py 挂载：

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('notes.urls')),
]

十一、创建模板文件

1) 列表页 `notes/templates/notes/list.html`

<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>留言列表</title>
    <style>
      body { font-family: Arial, sans-serif; background: #f4f6f8; padding: 24px; }
      .card { max-width: 760px; margin: 0 auto; background: white; padding: 20px; border-radius: 10px; }
      a { color: #1f78d1; }
      .item { padding: 10px 0; border-bottom: 1px solid #eee; }
    </style>
  </head>
  <body>
    <div class="card">
      <h1>留言板</h1>
      <p><a href="{% url 'message_create' %}">新增留言</a></p>
      {% for message in messages %}
        <div class="item">
          <strong>{{ message.name }}</strong>
          <p>{{ message.content }}</p>
          <small>{{ message.created_at }}</small>
        </div>
      {% empty %}
        <p>还没有留言，快来添加第一条吧。</p>
      {% endfor %}
    </div>
  </body>
</html>

2) 创建页 `notes/templates/notes/create.html`

<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>发表留言</title>
    <style>
      body { font-family: Arial, sans-serif; padding: 24px; }
      form { max-width: 760px; margin: 0 auto; }
      button { padding: 8px 16px; }
    </style>
  </head>
  <body>
    <h1>发表留言</h1>
    <form method="post">
      {% csrf_token %}
      {{ form.as_p }}
      <button type="submit">提交</button>
    </form>
    <p><a href="{% url 'message_list' %}">返回列表</a></p>
  </body>
</html>

csrf_token 必须保留，否则 POST 会被拒绝。

十二、把模型接入 Admin

编辑 notes/admin.py：

from django.contrib import admin
from .models import Message


@admin.register(Message)
class MessageAdmin(admin.ModelAdmin):
    list_display = ('name', 'content', 'created_at')
    search_fields = ('name', 'content')
    list_filter = ('created_at',)

然后创建管理员账号：

python manage.py createsuperuser

十三、运行项目并验证

1) 启动开发服务器

python manage.py runserver

2) 打开页面

用户页：http://127.0.0.1:8000/
新增页：http://127.0.0.1:8000/create/
后台：http://127.0.0.1:8000/admin/

3) 你应该看到

进入列表页可见“快来添加第一条吧”。
创建页可提交数据成功。
列表页能按时间倒序显示刚提交的数据。
后台可在 Message 列表看到同样的数据。

十四、最小可运行命令清单

# 1. 建库/更新
python manage.py makemigrations
python manage.py migrate

# 2. 创建管理员
python manage.py createsuperuser

# 3. 运行服务
python manage.py runserver

十五、常见报错与排查

1) `TemplateDoesNotExist`

常因模板路径不对。
确认是 notes/templates/notes/list.html（多一层 app 名）

2) `NoReverseMatch`

常因 {% url 'xxx' %} 与 urls.py 的 name 不一致。
确认 message_list、message_create 命名一致。

3) `OperationalError: no such table`

常因没执行 migrate。
先 makemigrations -> migrate 再启动服务。

4) 表单提交后报 403

检查是否缺少 {% csrf_token %}。

十六、下一步（建议）

给 Message 增加邮箱字段和校验规则
增加分页：Paginator
用静态文件放样式，不再写在模板内联
部署前切到 PostgreSQL/MySQL，关闭 DEBUG，并配置 ALLOWED_HOSTS

一段可发布到文章结尾的总结

完成这篇后，你已经从零到一搭建起了 Django 的完整应用基础：模型定义、表单校验、路由分发、视图处理、模板渲染、后台管理都已打通。这就是后续任何 Django 项目的基础骨架。