models.py
初识Django：搭建你的第一个Python网站
作为一名在互联网公司工作的后端开发者，我在过去的几年里参与了多个项目的开发工作。其中有一个项目让我印象深刻 —— 它是我们团队的第一个基于 Python 的 Web 项目，我们选择了 Django 来作为技术栈的核心框架。
当时，我们面临的主要挑战是需要快速搭建一个内容管理系统（CMS）的原型，时间紧、任务重，而团队成员大多有 Django 的使用经验或者至少熟悉 Python 基础。在这个背景下，我决定用 Django 搭建项目，并把它作为一次实践机会来深入理解这个经典框架的运作逻辑和适用场景。
这篇文章会以我的第一人称视角展开，分享我在完成这个项目中的完整过程 —— 从为什么选择 Django，到项目搭建的基本思路、代码实现细节、遇到的问题和解决办法，再到最终上线后的运维经验。希望我的这些经验能帮助刚入门的你少走弯路，在 Django 开发的路上更进一步。
问题描述：为什么需要快速搭建一个新系统？
事情得回到一年前，我们部门接了一个内部需求，需要为运营团队搭建一个简易的内容管理系统，用于管理产品介绍页面上的图文信息。虽然看起来不算复杂，但由于是内部工具且要尽早交付，留给我们的开发时间只有一周。
团队讨论之后，明确了几个关键点：
- 工期短：一周内必须上线基础功能，否则会影响运营计划。
- 数据模型较简单：只需要文章管理、分类标签、媒体资源上传等功能。
- 后台界面友好：非技术人员也需要方便地编辑内容。
- 未来可扩展性要强：后续可能会加入权限模块、审核机制等。
在比较了多种方案之后，我们一致认为 Django 是最佳选择。原因如下：
- 自带Admin后台：开箱即用，省去手写后台的时间；
- ORM封装成熟：数据库操作非常直观；
- 社区生态丰富：有很多第三方库可以直接复用；
- 开发效率高：适合快速迭代的产品形态。
确定技术路线之后，我开始着手搭建整个项目的基础架构，并逐步推进开发任务。这一过程并不是一帆风顺的，尤其是在实际部署过程中踩了不少坑。接下来我会一步步还原当时的开发流程，并结合真实的工作经历给出具体建议。
技术选型与架构设计：Django 为何适合这个项目
框架选型理由
选择 Django 有其历史渊源 —— 我之前在一个个人博客项目中尝试过 Flask，但发现当业务稍微复杂一点，Flask 需要手动配置的地方太多，比如登录验证、数据库迁移、后台管理等等，都需要一个个引入中间件来补足功能。相比之下，Django 天生就是一个“全栈框架”，它把开发中最常见的需求都整合到了一起，非常适合类似 CMS 这种中等复杂度但需要稳定结构的应用。
架构图概览
项目整体采用经典的 MVT（Model - View - Template）架构：
User <-> Controller(View) <-> Model(Database) -> 后台模板渲染
前端我们采用的是简单的 Bootstrap + jQuery 实现静态页面展示，后台完全依赖 Django 自带的 Admin 系统。由于需求明确且用户数量有限，我们没有一开始就集成 JWT 或 DRF（Django REST Framework），而是专注于实现内容管理的 CRUD 操作。
数据库设计简述
为了简化模型，我们设计了以下几个核心表：
class Category(models.Model):
name = models.CharField(max_length=50, unique=True)
class Article(models.Model):
title = models.CharField(max_length=200)
content = models.TextField()
category = models.ForeignKey(Category, on_delete=models.CASCADE)
pub_date = models.DateTimeField(auto_now_add=True)
class Media(models.Model):
file = models.FileField(upload_to='uploads/')
uploaded_at = models.DateTimeField(auto_now_add=True)
这样的模型非常清晰，通过 ForeignKey 实现关联关系，在后续查询和筛选时也十分灵活。同时，Django ORM 对字段定义的封装让后期添加索引、优化性能变得很轻松。
具体开发步骤详解
第一步：创建项目和应用
django-admin startproject cms_project
cd cms_project
python manage.py startapp articles
然后，我们需要将 articles 应用注册到 settings.py 中：
INSTALLED_APPS = [
...
'articles.apps.ArticlesConfig',
]
接着运行数据库迁移命令：
python manage.py makemigrations
python manage.py migrate
这样就初始化好了数据库结构。
第二步：配置Admin后台
为了让运营同事快速上手，我们重点配置了 Admin 系统。首先在 admin.py 中注册模型：
from django.contrib import admin
from .models import Article, Category, Media
@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
list_display = ['title', 'category', 'pub_date']
search_fields = ['title']
admin.site.register([Category, Media])
这段代码让运营人员可以在后台看到所有已发布的文章列表，还能搜索标题关键词，极大地提升了工作效率。
第三步：实现基本的API接口
虽然一开始并没有要求提供 API 接口给外部调用，但我们还是提前预留了基础结构。使用原生 views 写了一个最简接口：
from django.http import JsonResponse
from .models import Article
def article_list(request):
articles = Article.objects.all().values('id', 'title', 'content')
return JsonResponse(list(articles), safe=False)
配合 urls.py 注册路由：
path('api/articles/', views.article_list),
这个接口后来被前端团队用来对接移动端 App 内容展示部分，证明这种前置规划很有价值。
踩过的坑与解决方案记录
坑一：文件上传路径权限问题
刚开始实现 Media 模型时，我们用了默认的 FileField：
file = models.FileField(upload_to='uploads/')
但在生产环境中运行的时候，却发现上传失败 —— 提示路径不存在或权限错误。仔细排查后发现：
- 默认情况下，Django 不会自动创建
upload_to的目录； - 此外 Nginx + Gunicorn 部署模式下对上传目录的权限控制严格。
解决方法：
手动创建目标目录并设置权限：
mkdir media/uploads/ chown -R www-data:www-data media/修改 settings.py 添加上传根路径：
MEDIA_URL = '/media/' MEDIA_ROOT = os.path.join(BASE_DIR, 'media')
- 配置 nginx 加入 location 支持访问静态文件：
location /media/ { alias /home/app/cms_project/media/; }
这样做之后，图片上传恢复正常。
坑二：Admin 后台无法正常显示上传文件
这个问题出现在我们切换环境之后，发现 Admin 页面中的 Media 字段显示为空。经过查证才发现是在不同的部署阶段，MEDIA_ROOT 和 MEDIA_URL 配置出现了不一致。
解决方法：
确保在生产环境中使用的 settings.py 包含统一的配置，必要时可以拆分 settings_dev.py 和 settings_prod.py，使用环境变量来区分。
上线后效果评估与后续优化
项目按时上线，运营反馈良好。后台简洁高效，内容更新变得容易了很多。此外，我们的基础结构也为后续拓展打下了良好的基础。
性能表现方面：
- 平均响应时间控制在 200ms 左右；
- 使用缓存机制优化了首页文章列表的加载速度；
- 数据库通过加索引减少了慢查询。
可维护性方面：
- 项目结构清晰，易于团队协作；
- 后续接入 DRF 很顺利，接口文档自动生成；
- 出现故障时日志追踪定位很快。
给新人的一些建议和实战Tips
如果你刚开始学习 Django，或者正打算尝试用它来构建自己的 Web 应用，以下几点建议或许可以帮助你少走一些弯路：
1. 不要跳过 ORM 的学习，它是 Django 的灵魂之一
很多刚入行的朋友喜欢直接写 SQL，觉得这样更加直观。但实际上，Django ORM 提供了非常强大且易读的数据抽象能力，不仅节省时间，而且避免了许多潜在的注入攻击风险。
2. 学会善用内置功能，而不是重复造轮子
- 登录认证可以直接用
contrib.auth - 后台管理不要自己写，用 Admin 系统
- 表单提交用 Django Forms 验证器
- 日志、权限、CSRF 保护统统都有成熟的中间件支持
3. 合理划分项目结构，预留好未来的扩展空间
- 尽早分离 settings 文件为 dev/prod
- 单个 App 做单一职责，便于复用
- 接口和视图要区分开，为前后端分离做准备
4. 部署别忽视权限和路径配置，提前测试生产环境行为
本地运行顺畅不代表正式上线没问题。特别是涉及到用户上传文件、缓存、异步任务的场景，一定要在部署前模拟真实环境测试一遍。
结语：Django 是稳扎稳打的利器
回望这次项目，虽然只是一个小型 CMS，但它让我真正体会到了 Django 的强大之处：开箱即用、文档齐全、生态活跃。它不是最轻量的选择，也不是最炫酷的框架，但它足以让我们在有限时间内交付一个稳定、高效的 Web 应用。
对于正在成长中的后端开发者来说，掌握 Django，不仅是一次技能提升，更是工程思维训练的一个绝佳窗口。
如果你也在学习 Django 或者准备动手做一个项目，请记住一句话：先跑起来，再慢慢优化，比什么都重要。
最后，感谢你花时间阅读这篇技术实践文章。如果你有任何疑问，欢迎留言交流，我们一起成长 🌱。
评论 0