Django入门教程：搭建你的第一个Python网站

从一个“小项目”开始说起

作为一个有五年工作经验的后端工程师，我经常会回想刚入行时的情景。那时候我也和你现在一样，手握一本《Django权威指南》，坐在电脑前对着文档一头雾水。真正让我上手的，是一个看起来不起眼的小项目——公司内部的一个员工考勤管理系统。

这个系统的需求其实很清晰：记录员工打卡时间、统计出勤天数，并提供导出报表的功能。但就是这样一个看似简单的项目，却让我第一次完整地体验了从需求分析到部署上线的全过程。也正是这次经历，让我对 Django 这个 Python Web 框架有了更深的理解。

今天，我就想通过这篇文章，结合那次实战经验，带大家一步步搭建起自己的第一个 Django 网站。我们不会只是照着文档敲命令，而是会像在真实工作中那样去思考、设计、编码，甚至踩坑。

---

问题描述：为什么选 Django？我的第一个挑战

刚接到任务的时候，我其实也考虑过 Flask、Tornado，甚至是当时已经略显成熟的 FastAPI。但最终选择 Django，是因为它提供了开箱即用的 Admin 后台、ORM 支持以及完整的项目结构，对于中小型项目的快速开发来说非常友好。

不过，作为一个新手，我在搭建初期还是遇到了几个关键问题：

• 如何组织项目的目录结构？
• 数据模型如何设计，才能支持后续扩展？
• 用户认证和权限控制怎么做？
• 接口怎么对外暴露给前端？
• 上线部署需要注意哪些点？

这些问题没有一个标准答案，但在真实开发中是必须面对的。下面我就结合当时的实际开发流程，来详细讲讲我是怎么解决这些问题的。

---

解决方案：整体技术方案与架构设计

先说说整个项目的结构。我的目标很明确：轻量级、可维护性强、易于部署。

所以我采用的架构如下：

attendance_system/
├── attendance/              # 应用核心逻辑
│   ├── models.py            # 数据库模型
│   ├── views.py             # 业务逻辑层
│   ├── urls.py              # 路由配置
│   └── ...
├── users/                   # 用户模块（可复用）
├── config/                  # 配置文件目录
│   ├── settings.py          # 核心配置
│   ├── urls.py              # 全局路由
│   └── ...
└── manage.py                # 项目启动脚本

这种结构的好处在于职责分明，未来即使要拆分成微服务也很方便。

至于数据库，考虑到后期可能会做跨部门数据隔离，我在设计表的时候就预留了 department 字段。比如打卡记录表大致结构如下：

class AttendanceRecord(models.Model):
    user = models.ForeignKey(User, on_delete=models.CASCADE)
    timestamp = models.DateTimeField(auto_now_add=True)
    status = models.CharField(max_length=10, default='normal')  # normal, late, early_leave, absent
    department = models.CharField(max_length=64)

    def __str__(self):
        return f"{self.user.username} - {self.timestamp}"

这样做的好处是，后续可以很方便地按部门筛选数据。

---

代码实践：从零开始搭建网站

步骤一：创建项目

首先确保你安装了 Python 和 pip，推荐使用 Python 3.8 或以上版本。然后安装 Django：

pip install django

接下来创建项目：

django-admin startproject attendance_system
cd attendance_system

此时你会看到 manage.py 文件，它是 Django 的管理入口。

步骤二：创建应用

Django 鼓励将不同功能模块划分成“app”，我们来创建两个应用：

python manage.py startapp attendance
python manage.py startapp users

记得把这两个 app 添加到 INSTALLED_APPS 中：

# config/settings.py

INSTALLED_APPS = [
    ...
    'users',
    'attendance',
]

步骤三：定义模型并初始化数据库

以用户登录为例，在 users/models.py 定义一个基础用户信息表（这里为了简化，直接继承 Django 自带的 User）：

from django.contrib.auth.models import AbstractUser

class CustomUser(AbstractUser):
    phone = models.CharField(max_length=15, blank=True, null=True)
    department = models.CharField(max_length=64, blank=True, null=True)

接着修改 settings.py：

AUTH_USER_MODEL = 'users.CustomUser'

运行迁移命令：

python manage.py makemigrations
python manage.py migrate

步骤四：添加后台管理界面

Django 最强大的地方之一就是内置了 Admin 后台，我们可以快速注册模型：

# users/admin.py
from django.contrib import admin
from .models import CustomUser

admin.site.register(CustomUser)

创建管理员账号：

python manage.py createsuperuser

访问 /admin 就可以看到我们的自定义用户后台了。

步骤五：实现接口

我们可以通过 Django REST framework 快速暴露接口：

pip install djangorestframework

然后在 urls.py 加入 API 路由：

from rest_framework.routers import DefaultRouter
from attendance.views import AttendanceViewSet

router = DefaultRouter()
router.register(r'attendance', AttendanceViewSet, basename='attendance')

urlpatterns += router.urls

对应的 viewset 示例：

from rest_framework import viewsets
from attendance.models import AttendanceRecord
from attendance.serializers import AttendanceSerializer

class AttendanceViewSet(viewsets.ModelViewSet):
    queryset = AttendanceRecord.objects.all()
    serializer_class = AttendanceSerializer

这样我们就拥有了一个支持增删改查的 RESTful API 接口。

---

踩坑经验：开发过程中遇到的真实问题

别看现在写起来顺理成章，当年可真是踩了不少坑。这里我想特别提几个容易忽略的问题，希望能帮你在路上少走弯路。

坑 1：自定义用户模型的导入顺序问题

一开始我没有在 settings.py 设置 AUTH_USER_MODEL，导致数据库无法正确关联。后来虽然设置了，但由于旧 migrations 存在冲突，执行失败。解决方法是彻底删除 migration 文件和 db.sqlite3，再重新生成一次（适用于开发阶段）。

坑 2：并发写入冲突（PostgreSQL 使用注意）

我们在开发后期切换到了 PostgreSQL，结果在高并发打卡场景下出现了死锁。这是因为多个请求同时向同一个记录发起更新操作。我们采取了两种策略：

• 使用 select_for_update() 对记录加锁；
• 引入 Redis 缓存队列异步处理部分写操作。

如果你的网站并发不高，这个问题可能不会出现。但提前了解数据库事务机制，永远都不是坏事。

坑 3：跨域问题困扰接口调试

前后端分离后，前端 Vue 应用跑在 localhost:8080，后端在 8000，跨域成了问题。解决方案是引入 Django-cors-headers：

pip install django-cors-headers

然后在 settings.py 加入中间件：

MIDDLEWARE = [
    ...
    'corsheaders.middleware.CorsMiddleware',
    ...
]

CORS_ORIGIN_ALLOW_ALL = False
CORS_ORIGIN_WHITELIST = (
    'http://localhost:8080',
)

---

效果总结：从交付到上线

这个考勤系统最终按时交付上线，运行一年零故障。以下是几个关键指标：

• 日均请求量约 2000 次，主要集中在上下班高峰时段；
• 平均响应时间低于 150ms；
• 同期上线的还有 HR 模块，基于相同框架结构，只用了两周完成重构；
• 管理员可通过 Admin 后台一键导出 Excel 报表，极大提升了工作效率。

最重要的是，这套系统后来被推广到了其他分公司使用，还接入了钉钉考勤数据接口，真正做到了“小系统大作用”。

---

经验分享：写给正在学习 Django 的你

说了这么多，都是我在真实工作中摸爬滚打的经验，真心希望你能少走一些弯路。

✅ 开发建议

1. 不要一开始就追求完美结构：很多人喜欢把项目拆得很细，但 Django 的哲学是“约定优于配置”。前期保持简单清晰更重要。
2. 合理使用 ORM，避免 SQL 注入：Django ORM 很强大，但也有一些性能瓶颈，建议配合 .select_related() 和 .prefetch_related() 提升效率。
3. 善用 Admin 后台：很多管理后台都不用重新开发，稍加定制即可使用。
4. 尽早集成日志系统：上线前一定记得加上 logging 配置，否则排查问题会很痛苦。

🛠️ 生产部署技巧

1. 使用 gunicorn + nginx 部署：Gunicorn 是 Python 应用的事实标准服务器，Nginx 可以做静态资源代理和负载均衡。
2. 开启 DEBUG=False 模式：正式环境中一定要关闭 Debug 模式，防止敏感信息泄露。
3. 使用环境变量管理敏感配置：可以用 python-decouple 或 django-environ 加载 .env 文件。
4. 配置数据库连接池：生产环境推荐 PostgreSQL + psycopg2，也可以用 dj-database-url 简化配置。
5. 定期执行 DB 备份和清理任务：使用 django-extensions 中的 management commands 可以帮你自动化这些工作。

---

结语：Django 的魅力不止于此

Django 已经陪伴我走过了很多个项目，从最初的单体应用，到现在的微服务架构，它始终是我后端开发工具箱中最不可或缺的一部分。它的设计理念“Batteries included”让开发者能够专注业务本身，而不是反复造轮子。

无论你是想构建博客系统、CRM、ERP，还是更复杂的 Web 平台，Django 都能胜任。它不仅适合快速原型开发，也具备足够的灵活性应对长期演进。

如果你刚刚开始学习 Web 开发，不妨从 Django 开始，跟着项目做一遍，你会发现：原来写一个网站也没那么难！

愿你在 Django 的旅程中，一路顺利，越写越快乐 😄