Django 快速入门与 MVT 实战

# 创建项目目录
mkdir learning_log && cd learning_log

# 创建虚拟环境（Python 3）
python3 -m venv ll_env

# 激活虚拟环境
# macOS/Linux:
source ll_env/bin/activate
# Windows:
# ll_env\Scripts\activate

# 升级 pip 并安装 Django
pip install --upgrade pip
pip install django>=4.2,<5.0

# 验证安装
python -m django --version
# 输出示例: 4.2.11

# ★ 关键：末尾的句点 . 让 Django 在当前目录创建项目，而不是新建子目录
django-admin startproject learning_log .

# 查看生成的项目结构
ls -la

# 创建数据库并应用默认迁移（内置应用的表结构）
python manage.py migrate

# 输出示例：
# Operations to perform:
#   Apply all migrations: admin, auth, contenttypes, sessions
# Running migrations:
#   Applying contenttypes.0001_initial... OK
#   Applying auth.0001_initial... OK
#   Applying admin.0001_initial... OK
#   ...

# 启动 Django 开发服务器
python manage.py runserver

# 输出：
# Watching for file changes with StatReloader...
# Performing system checks...
#
# System check identified no issues (0 silenced).
# June 07, 2026 - 10:00:00
# Django version 4.2.11, using settings 'learning_log.settings'
# Starting development server at http://127.0.0.1:8000/
# Quit the server with CONTROL-C.

# 创建名为 learning_notes 的应用程序
python manage.py startapp learning_notes

# 生成的 app 目录结构：
# learning_notes/
# ├── __init__.py
# ├── admin.py       # Admin 后台注册
# ├── apps.py        # App 配置
# ├── models.py      # ★ 数据模型定义
# ├── tests.py       # 单元测试
# └── views.py       # ★ 视图函数

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


class Topic(models.Model):
    """用户学习的主题"""
    text = models.CharField(max_length=200)          # 主题文本，最大长度200字符
    date_added = models.DateTimeField(auto_now_add=True)  # 自动记录创建时间

    class Meta:
        verbose_name = '主题'                          # 单数形式显示名
        verbose_name_plural = '主题'                   # 复数形式显示名（Admin后台使用）

    def __str__(self):
        """返回模型的字符串表示，用于 Admin 和 Shell 显示"""
        return self.text

# learning_log/settings.py

INSTALLED_APPS = [
    # Django 内置应用
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    # ★ 我的应用
    'learning_notes',   # 注册我们的学习笔记应用
]

# 让 Django 检测模型变更并生成迁移文件
python manage.py makemigrations learning_notes

# 输出：
# Migrations for 'learning_notes':
#   learning_notes/migrations/0001_initial.py
#     - Create model Topic

# 将迁移应用到数据库（实际创建表）
python manage.py migrate

# 输出：
# Applying learning_notes.0001_initial... OK

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


class Topic(models.Model):
    """用户学习的主题"""
    text = models.CharField(max_length=200)
    date_added = models.DateTimeField(auto_now_add=True)

    class Meta:
        verbose_name_plural = '主题'

    def __str__(self):
        return self.text


class Entry(models.Model):
    """学到的有关某个主题的具体知识"""
    # ★ ForeignKey 定义多对一关系：多个 Entry 属于一个 Topic
    topic = models.ForeignKey(
        Topic,
        on_delete=models.CASCADE,  # 删除主题时，级联删除其所有条目
        related_name='entries',     # 反向查询名称：topic.entries.all()
    )
    text = models.TextField()                           # 长文本字段
    date_added = models.DateTimeField(auto_now_add=True)

    class Meta:
        verbose_name_plural = '条目'
        ordering = ['-date_added']                       # 默认按时间倒序排列

    def __str__(self):
        """返回前50个字符作为简短表示"""
        if len(self.text) > 50:
            return self.text[:50] + "..."
        return self.text

python manage.py makemigrations learning_notes
python manage.py migrate

python manage.py createsuperuser

# 交互式输入：
# Username: admin
# Email address: admin@example.com
# Password: ********
# Password (again): ********
# Superuser created successfully.

# learning_notes/admin.py
from django.contrib import admin
from .models import Topic, Entry


@admin.register(Topic)
class TopicAdmin(admin.ModelAdmin):
    """Topic 模型的 Admin 配置"""
    list_display = ('text', 'date_added')           # 列表页显示的字段
    search_fields = ('text',)                        # 搜索框搜索的字段
    list_filter = ('date_added',)                    # 右侧筛选栏


@admin.register(Entry)
class EntryAdmin(admin.ModelAdmin):
    """Entry 模型的 Admin 配置"""
    list_display = ('topic', 'date_added', 'text_preview')
    list_filter = ('topic', 'date_added')
    search_fields = ('text',)
    raw_id_fields = ('topic',)                       # 外键以 ID 输入框显示（数据量大时有用）

    @admin.display(description='内容预览')           # 自定义列的显示名称
    def text_preview(self, obj):
        return obj.text[:50] + '...' if len(obj.text) > 50 else obj.text

# 进入 Django Shell（相比普通 Python Shell，它预加载了 Django 环境）
python manage.py shell

# ===== 在 Django Shell 中执行 =====

# 导入模型
from learning_notes.models import Topic, Entry

# 1. 查询所有主题
topics = Topic.objects.all()
for topic in topics:
    print(topic.id, topic.text, topic.date_added)
# 输出: 1 Python基础 2026-06-07 10:30:00
#       2 Django框架 2026-06-07 11:00:00

# 2. 获取单个对象（注意：get() 如果找不到会抛异常！）
try:
    topic = Topic.objects.get(id=1)
    print(topic)  # 输出: Python基础
except Topic.DoesNotExist:
    print("主题不存在")

# 3. 过滤查询（返回 QuerySet，即使结果为空也不会报错）
python_topics = Topic.objects.filter(text__icontains='python')
print(python_topics.count())  # 输出匹配数量

# 4. 通过外键反向查询（related_name 的威力）
topic = Topic.objects.get(id=1)
entries = topic.entries.all()         # 获取该主题下的所有条目
recent_entries = topic.entries.order_by('-date_added')[:5]  # 最新5条

# 5. 创建新条目
entry = Entry()
entry.topic = topic
entry.text = "今天学习了 Django 的 MVT 架构..."
entry.save()

# 6. 一行代码创建（create 方法）
Entry.objects.create(
    topic=topic,
    text="Django Admin 真的很强大！"
)

# 7. 删除条目
entry.delete()

path(route, view, kwargs=None, name=None)

# learning_log/urls.py（项目主路由）
from django.contrib import admin
from django.urls import path, include

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

    # 方式一：直接导入视图函数（适合小型项目）
    # from learning_notes.views import index
    # path('', index, name='index'),

    # 方式二：使用 include 分发到子应用路由（★ 推荐）
    path('', include('learning_notes.urls')),
]

# learning_notes/urls.py（应用子路由）
from django.urls import path
from . import views

app_name = 'learning_notes'  # 命名空间，避免不同 app 的 name 冲突

urlpatterns = [
    # 首页：显示所有主题
    path('', views.index, name='index'),

    # 主题列表页
    path('topics/', views.topics, name='topics'),

    # 主题详情页：<int:topic_id> 捕获 URL 中的整数参数
    path('topics/<int:topic_id>/', views.topic, name='topic'),
]

# learning_notes/views.py
from django.shortcuts import render, get_object_or_404
from .models import Topic, Entry


def index(request):
    """项目首页"""
    return render(request, 'learning_notes/index.html')


def topics(request):
    """显示所有主题"""
    topics = Topic.objects.order_by('date_added')  # 按创建时间排序
    context = {'topics': topics}                    # 构建上下文字典
    return render(request, 'learning_notes/topics.html', context)


def topic(request, topic_id):
    """
    显示单个主题及其所有条目

    Args:
        request: HTTP 请求对象
        topic_id: 从 URL 捕获的主题 ID（整数）
    """
    # get_object_or_404: 获取对象或返回 404 页面（比 try-except 更优雅）
    topic = get_object_or_404(Topic, id=topic_id)

    # 通过外键反向查询获取该主题的所有条目（按时间倒序）
    entries = topic.entries.order_by('-date_added')

    context = {
        'topic': topic,
        'entries': entries,
    }
    return render(request, 'learning_notes/topic.html', context)

render(request, template_name, context=None, content_type=None, status=None)

<!-- ❌ 硬编码 URL（脆弱，改动成本高） -->
<a href="/topics/1/">查看主题</a>

<!-- ✅ 使用 {% url %} 标签反向解析（健壮，自动跟随路由变化） -->
<a href="{% url 'learning_notes:topic' topic_id=topic.id %}">查看主题</a>

# 在视图中反向解析 URL
from django.urls import reverse
from django.http import HttpResponseRedirect

def some_view(request):
    # 重定向到指定命名的 URL
    return HttpResponseRedirect(reverse('learning_notes:topics'))

<!-- ===== 变量与注释 ===== -->
<p>{{ username }}</p>
{# 这是模板注释，不会出现在最终的 HTML 中 #}

<!-- ===== 条件判断 ===== -->
{% if user.is_authenticated %}
    <p>欢迎回来，{{ user.username }}！</p>
{% elif user.is_new %}
    <p>欢迎新用户！</p>
{% else %}
    <p><a href="{% url 'login' %}">请登录</a></p>
{% endif %}

<!-- ===== 循环迭代 ===== -->
<ul>
{% for topic in topics %}
    <li>{{ forloop.counter }}. {{ topic.text }}</li>
    <!-- forloop.counter: 当前是第几次循环（从1开始） -->
    <!-- forloop.counter0: 从0开始 -->
    <!-- forloop.first / last: 是否是第一个/最后一个 -->
{% empty %}
    <li>暂无主题，<a href="{% url 'new_topic' %}">立即创建</a></li>
{% endfor %}
</ul>

<!-- ===== URL 反向解析 ===== -->
<a href="{% url 'learning_notes:topic' topic_id=topic.id %}">
    {{ topic.text }}
</a>

<!-- ===== 模板继承（稍后详述） ===== -->
{% extends "learning_notes/base.html" %}
{% block title %}主题详情{% endblock %}
{% block content %}...{% endblock %}

<!-- ===== 静态文件加载 ===== -->
{% load static %}
<link rel="stylesheet" href="{% static 'css/style.css' %}">
<img src="{% static 'images/logo.png' %}" alt="Logo">

<!-- learning_notes/templates/learning_notes/base.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{% block title %}学习笔记{% endblock %}</title>
</head>
<body>
    <!-- 导航栏 -->
    <nav>
        <a href="{% url 'learning_notes:index' %}">首页</a>
        <a href="{% url 'learning_notes:topics' %}">主题</a>
    </nav>

    <!-- 主要内容区域：子模板将在这里注入内容 -->
    <main>
        {% block content %}
        <!-- 默认内容（子模板未覆写时显示） -->
        <p>欢迎来到学习笔记！</p>
        {% endblock %}
    </main>

    <!-- 页脚 -->
    <footer>
        <p>&copy; 2026 学习笔记. All rights reserved.</p>
    </footer>
</body>
</html>

<!-- learning_notes/templates/learning_notes/topics.html -->
{% extends "learning_notes/base.html" %}

{% block title %}主题列表 - 学习笔记{% endblock %}

{% block content %}
<h1>所有主题</h1>

<ul>
{% for topic in topics %}
    <li>
        <a href="{% url 'learning_notes:topic' topic_id=topic.id %}">
            {{ topic.text }}
        </a>
        <small>({{ topic.date_added|date:"Y-m-d H:i" }})</small>
    </li>
{% empty %}
    <li>暂无主题。<a href="#">创建新主题</a></li>
{% endfor %}
</ul>
{% endblock %}

<!-- learning_notes/templates/learning_notes/topic.html -->
{% extends "learning_notes/base.html" %}

{% block title %}{{ topic.text }} - 学习笔记{% endblock %}

{% block content %}
<h1>{{ topic.text }}</h1>
<p>创建于：{{ topic.date_added|date:"Y年m月d日 H:i" }}</p>

<h2>条目列表</h2>
{% for entry in entries %}
    <article class="entry">
        <p class="entry-time">{{ entry.date_added|date:"m-d H:i" }}</p>
        <p class="entry-text">{{ entry.text|linebreaks }}</p>
    </article>
{% empty %}
    <p>该主题下暂无条目。</p>
{% endfor %}

<p>
    <a href="{% url 'learning_notes:topics' %}">← 返回主题列表</a>
</p>
{% endblock %}

learning_notes/
└── templates/                    # 模板根目录
    └── learning_notes/           # ★ 以应用名命名的子目录（避免冲突！）
        ├── base.html             # 父模板
        ├── index.html            # 首页
        ├── topics.html           # 主题列表页
        └── topic.html            # 主题详情页

# learning_log/settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'learning_notes',              # ★ 注册我们的应用
]

# 数据库配置（默认 SQLite，开发环境够用）
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

# 语言和时区设置
LANGUAGE_CODE = 'zh-hans'
TIME_ZONE = 'Asia/Shanghai'
USE_I18N = True
USE_TZ = True

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


class Topic(models.Model):
    """学习主题"""
    text = models.CharField(max_length=200)
    date_added = models.DateTimeField(auto_now_add=True)

    class Meta:
        verbose_name_plural = '主题'

    def __str__(self):
        return self.text


class Entry(models.Model):
    """主题下的具体条目"""
    topic = models.ForeignKey(
        Topic,
        on_delete=models.CASCADE,
        related_name='entries'
    )
    text = models.TextField()
    date_added = models.DateTimeField(auto_now_add=True)

    class Meta:
        verbose_name_plural = '条目'
        ordering = ['-date_added']

    def __str__(self):
        return self.text[:50] + '...' if len(self.text) > 50 else self.text

# learning_notes/admin.py
from django.contrib import admin
from .models import Topic, Entry


class EntryInline(admin.TabularInline):
    """在 Topic 编辑页面内联编辑 Entry"""
    model = Entry
    extra = 1  # 显示 1 个空白 Entry 表单供添加


@admin.register(Topic)
class TopicAdmin(admin.ModelAdmin):
    list_display = ('text', 'date_added')
    search_fields = ('text',)
    inlines = [EntryInline]  # 内联编辑关联的条目


@admin.register(Entry)
class EntryAdmin(admin.ModelAdmin):
    list_display = ('topic', 'text_preview', 'date_added')
    list_filter = ('topic', 'date_added')

    @admin.display(description='内容摘要')
    def text_preview(self, obj):
        return obj.text[:50] + '...' if len(obj.text) > 50 else obj.text

# learning_log/urls.py（项目主路由）
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('learning_notes.urls')),  # 分发给应用的路由
]

# learning_notes/urls.py（应用子路由）
from django.urls import path
from . import views

app_name = 'learning_notes'

urlpatterns = [
    path('', views.index, name='index'),
    path('topics/', views.topics, name='topics'),
    path('topics/<int:topic_id>/', views.topic, name='topic'),
]

# learning_notes/views.py
from django.shortcuts import render, get_object_or_404
from .models import Topic


def index(request):
    """首页"""
    return render(request, 'learning_notes/index.html')


def topics(request):
    """显示所有主题"""
    topics = Topic.objects.order_by('date_added')
    context = {'topics': topics}
    return render(request, 'learning_notes/topics.html', context)


def topic(request, topic_id):
    """显示单个主题及其条目"""
    topic = get_object_or_404(Topic, id=topic_id)
    entries = topic.entries.order_by('-date_added')
    context = {
        'topic': topic,
        'entries': entries,
    }
    return render(request, 'learning_notes/topic.html', context)

<!-- learning_notes/templates/learning_notes/base.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{% block title %}学习笔记{% endblock %}</title>
    <style>
        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
               max-width: 800px; margin: 0 auto; padding: 20px; line-height: 1.6; }
        nav { background: #f5f5f5; padding: 10px 20px; border-radius: 8px; margin-bottom: 20px; }
        nav a { margin-right: 15px; text-decoration: none; color: #333; }
        nav a:hover { color: #007bff; }
        h1 { color: #333; border-bottom: 2px solid #007bff; padding-bottom: 10px; }
        ul { list-style: none; padding: 0; }
        li { padding: 10px; border-bottom: 1px solid #eee; }
        li:hover { background: #f9f9f9; }
        article.entry { background: #fafafa; padding: 15px; border-radius: 8px; margin-bottom: 15px; }
        .entry-time { color: #888; font-size: 0.9em; }
        .entry-text { margin-top: 5px; }
    </style>
</head>
<body>
    <nav>
        <strong>📝 学习笔记</strong>
        <a href="{% url 'learning_notes:index' %}">首页</a>
        <a href="{% url 'learning_notes:topics' %}">主题</a>
        <a href="/admin/">管理</a>
    </nav>

    {% block content %}
    {% endblock %}
</body>
</html>

<!-- learning_notes/templates/learning_notes/index.html -->
{% extends "learning_notes/base.html" %}

{% block title %}首页 - 学习笔记{% endblock %}

{% block content %}
<div style="text-align: center; padding: 60px 20px;">
    <h1 style="border: none;">📝 欢迎来到学习笔记</h1>
    <p style="font-size: 1.2em; color: #666;">
        记录你的学习旅程，整理知识体系
    </p>
    <br>
    <a href="{% url 'learning_notes:topics' %}"
       style="display: inline-block; padding: 12px 30px; background: #007bff;
              color: white; border-radius: 8px; text-decoration: none;">
        浏览所有主题 →
    </a>
</div>
{% endblock %}

<!-- learning_notes/templates/learning_notes/topics.html -->
{% extends "learning_notes/base.html" %}

{% block title %}主题列表 - 学习笔记{% endblock %}

{% block content %}
<h1>所有主题</h1>

{% if topics %}
<ul>
    {% for topic in topics %}
    <li>
        <a href="{% url 'learning_notes:topic' topic_id=topic.id %}">
            📚 {{ topic.text }}
        </a>
        <span style="color: #888; font-size: 0.9em;">
            ({{ topic.date_added|date:"Y-m-d" }})
        </span>
    </li>
    {% endfor %}
</ul>
{% else %}
<p>暂无主题。</p>
{% endif %}
{% endblock %}

<!-- learning_notes/templates/learning_notes/topic.html -->
{% extends "learning_notes/base.html" %}

{% block title %}{{ topic.text }} - 学习笔记{% endblock %}

{% block content %}
<h1>📚 {{ topic.text }}</h1>
<p style="color: #666;">创建于：{{ topic.date_added|date:"Y年m月d日 H:i" }}</p>

<hr>

<h2>📝 学习条目 (共 {{ entries|length }} 条)</h2>

{% for entry in entries %}
<article class="entry">
    <div class="entry-time">🕐 {{ entry.date_added|date:"Y-m-d H:i" }}</div>
    <div class="entry-text">{{ entry.text|linebreaks }}</div>
</article>
{% empty %}
<p style="color: #888; padding: 20px; text-align: center;">
    该主题下暂无条目。
</p>
{% endfor %}

<br>
<p>
    <a href="{% url 'learning_notes:topics' %}" style="color: #007bff;">
        ← 返回主题列表
    </a>
</p>
{% endblock %}

# 1. 执行数据库迁移（首次或模型变更后）
python manage.py makemigrations
python manage.py migrate

# 2. 创建管理员账户（如果还没有）
python manage.py createsuperuser

# 3. 启动开发服务器
python manage.py runserver

# ❌ 错误：创建了嵌套目录 learning_log/learning_log/
django-admin startproject learning_log

# ✅ 正确：在当前目录创建项目
django-admin startproject learning_log .

# ❌ Django 2.0+ 报错：TypeError: __init__() missing 1 required argument: 'on_delete'
topic = models.ForeignKey(Topic)

# ✅ 正确：必须指定删除策略
topic = models.ForeignKey(Topic, on_delete=models.CASCADE)

# ❌ 错误：直接放在 templates 根目录（可能导致模板冲突）
templates/
├── base.html
├── topics.html

# ✅ 正确：放在以应用名为子目录下
templates/
└── learning_notes/
    ├── base.html
    ├── topics.html

# ❌ 危险：如果 id=999 不存在，会抛出 Topic.DoesNotExist 异常（500 错误）
topic = Topic.objects.get(id=999)

# ✅ 安全：使用 get_object_or_404，不存在时自动返回友好的 404 页面
from django.shortcuts import get_object_or_404
topic = get_object_or_404(Topic, id=999)

<!-- ❌ 脆弱：URL 路径改变后所有链接失效 -->
<a href="/topics/{{ topic.id }}/">

<!-- ✅ 健壮：使用 reverse 解析，URL 改变只需修改 urls.py 一处 -->
<a href="{% url 'learning_notes:topic' topic_id=topic.id %}">

# ❌ 错误：应用未注册，makemigrations 无法检测到模型
INSTALLED_APPS = [
    # ... 其他应用
    # 缺少 'learning_notes'
]

# ✅ 正确：注册应用
INSTALLED_APPS = [
    # ... 其他应用
    'learning_notes',
]

<!-- ⚠️ 注意：Django 模板中的变量默认是不可变的 -->
{% with new_var=old_var|upper %}
    {{ new_var }}  <!-- 这里可以使用新变量 -->
{% endwith %}
<!-- old_var 仍然是原来的值 -->

# 当多人同时修改模型导致迁移冲突时：
python manage.py makemigrations --merge
# Django 会尝试自动合并迁移文件（有时需要手动解决）