企业官网建设流程全解析

不少人学Django都会卡在同一个地方：教程翻了一堆，视频刷了不少，一旦要自己动手做一个完整项目，就不知道从哪里下手了。“基于Python+Django的员工管理系统”这类项目之所以常年热门，就是因为它足够典型——增删改查、权限控制、分页搜索、部署上线，几乎把Django日常开发会用到的核心能力全部覆盖了一遍。而且员工的“增删改查”足够接地气，比TodoList有说服力，比电商系统门槛低，非常适合用来打通从源码阅读到部署上线的完整链路。

这篇文章就围绕这个项目，从系统设计、源码结构、核心代码实现，再到部署文档的落地，把一套完整可运行的员工管理系统的关键细节拆开讲清楚。很多人拿到一个项目源码，第一反应是“我能跑起来，但看不懂”，所以我会重点讲代码为什么要这么写、部署时那些文档里不会写清楚的坑在哪里，尽量让你读完既能把项目跑起来，也能把项目讲明白——无论是面试还是课程设计答辩都够用。

1. 项目整体设计：为什么选Django，系统功能怎么拆

1.1 为什么用Django做员工管理系统

市面上能开发Web应用的框架很多，Python生态里比较常见的就是Flask、FastAPI、Django这三个。做员工管理系统这类偏传统的管理类Web应用，Django其实是首选，原因很直接：它自带的东西太多了。

员工管理系统最核心的需求就是数据的管理——员工信息要存数据库、要有后台管理界面、要有登录认证和权限区分、要有表单校验。如果用Flask实现，这些都需要自己找第三方库拼装，Flask本身只负责路由和视图这一层，数据库要用SQLAlchemy，表单要用WTForms，认证要用Flask-Login，一套组合下来光研究包之间的兼容性就要花不少时间。FastAPI则更偏向API服务，它的异步性能和自动生成接口文档的能力很突出，但如果你是做传统的服务端渲染页面，它反而不如Django方便。

Django是“全家桶”思路，内置了ORM、Admin后台、认证系统、表单处理、模板引擎，甚至分页、消息提示、CSRF防护这些细节都做好了。做一个员工管理系统，Django把这些基础能力直接给你，你只需要专注于业务本身的实现。另外很重要的一点是，Django的Admin后台对这类系统来说几乎是天然的管理界面。即使你不想用Admin作为主要界面，它在调试数据、维护字典表、管理用户权限的时候也非常顺手。

从面试和学习的角度看，Django的MTV架构是高频考点，员工管理系统又是最能体现MTV架构实际应用的项目。把这种经典项目吃透，性价比非常高。

1.2 功能模块与数据模型设计

拿到一个员工管理系统项目，先不要急着看代码，第一步应该是看数据模型。数据模型决定了系统能做什么、不能做什么，也是后面所有业务逻辑的基础。

一套标准的员工管理系统，核心模块一般包含这几块：

• 员工信息管理：员工基本信息的增删改查，包括工号、姓名、性别、出生日期、手机号、邮箱、入职日期、在职状态等。
• 部门管理：部门名称、部门编号、负责人等，员工和部门是多对一关系。
• 用户认证与权限：系统的登录用户（通常就是HR或管理员），不同角色的权限不同。
• 辅助功能：比如按部门筛选员工、搜索员工、分页显示、导出Excel等，这些虽然不是最核心的，但直接影响系统好不好用。

在设计数据模型时，员工表和部门表是最重要的。这里给出一份比较合理的模型设计，也是这类项目里常见的设计方案：

部门表可以直接用Django的模型定义，关键字段包括名称、编码、负责人、创建时间。注意编码要做唯一约束，因为部门编码在后续的人员统计、报表导出中经常作为关联字段。

员工表是系统的核心，字段会相对多一些。我在实际项目里建议至少包含以下字段：

这里有几个设计上的细节值得说一下。

第一个是工号要不要用自增主键。如果员工表和主键id耦合，一旦数据被删除，id就空出来了，后续做数据对接和审计会有麻烦。更好的做法是工号独立成一个有业务含义的字段，主键仍然保留Django自带的id。

第二个是外键的on_delete参数。很多人初学者直接默认什么都不写，但Django 2.0以后外键必须显式设置on_delete。对于部门迭代删除了，员工还在的情况，建议用PROTECT或者SET_NULL。如果设置为CASCADE，部门一删除，整个部门下面的员工就全没了，这在真实业务中是非常危险的操作。我的习惯是：员工表关联部门的外键用PROTECT，保护数据不被级联删除。

第三个是status字段用IntegerField还是CharField加choices。choices是Django的标准做法，输入的时候限制在可选范围内，可读性也好。gender字段同理。

1.3 MTV模式在项目中的具体落地

Django的MTV模式是面试常问的内容，也是理解Django项目结构的钥匙。M是Model，负责数据层；T是Template，负责展示层；V是View，负责业务逻辑层；URL路由则负责把用户的请求分发到对应的View。

很多人把Django的MTV和经典的MVC做对比。MVC里Controller负责业务逻辑，而Django的View承担了类似Controller的角色。Template对应View，Model对应Model。所以Django严格来说是MTV，不是传统意义的MVC。面试时讲清楚这一点，比背概念更有说服力。

MTV在员工管理系统中是怎么落地的？以一个最简单的功能——员工列表展示为例，完整链路是这样的：

用户在浏览器输入URL，比如/employee/list/。 Django的URLConf根据匹配规则，把请求交给对应的View函数。 View从数据库查询员工数据（Model层）。 View把数据通过上下文传给Template。 Template渲染成HTML，返回给用户浏览器。

这个流程看起来简单，但实际编码时有很多容易踩坑的地方。比如查询数据库，新手最容易犯的错误是在视图里写复杂的原生SQL，而Django ORM提供了一个非常优雅的链式查询方式。再比如模板渲染，新手经常把业务逻辑写在模板里，模板里写一堆{% if %}嵌套，看起来能跑，但代码维护起来极其痛苦。真正的MTV实践是把模板保持干净，只做展示和数据遍历，把判断逻辑放进View里处理后再传给模板。

我在做这个项目的时候，还专门用了Django的CreateView、UpdateView、DeleteView这些基于类的视图。泛化视图能省很多代码，但坦白说，新手阶段用函数视图更好理解流程。当你能用函数视图把增删改查写熟练了，再切换到类视图会轻松很多，因为你知道背后做了什么。

2. 源码结构分析与核心代码讲解

2.1 项目目录结构与源码组织

把一个Django项目源码拿到手，先看目录结构，这是读懂一个项目最快的方式。标准Django项目，经过合理的模块拆分后，目录结构应该是清晰且分层明确的。

这里展示一个规范的员工管理系统目录结构：

employee_system/ ├── manage.py # Django项目管理入口 ├── requirements.txt # 项目依赖清单 ├── config/ # 项目配置目录 │ ├── __init__.py │ ├── settings/ │ │ ├── base.py # 基础配置 │ │ ├── dev.py # 开发环境配置 │ │ └── prod.py # 生产环境配置 │ ├── urls.py # 全局路由配置 │ └── wsgi.py ├── apps/ │ ├── employees/ # 员工模块 │ │ ├── models.py │ │ ├── views.py │ │ ├── urls.py │ │ ├── forms.py │ │ ├── admin.py │ │ ├── migrations/ │ │ └── templates/employees/ │ ├── departments/ # 部门模块 │ └── users/ # 用户认证模块 ├── static/ # 全局静态资源 ├── media/ # 用户上传文件 └── templates/ # 全局模板目录

这种目录结构不是随便拍的，每个目录背后都有实际考量。第一，多app拆分。把员工、部门、用户认证拆成独立app，目的是高内聚、低耦合。员工模块只关心员工自己的业务，部门模块只关心部门，将来若要加考勤、工资模块，只需要再新增一个app，不需要改动现有模块。

第二，settings拆分成多个文件。很多项目把settings.py写成一个千行大文件，开发环境和生产环境混在一起，这是灾难的源头。拆分后，base.py放公共配置，dev.py放调试相关，prod.py放生产环境的数据库和静态资源配置。这样部署的时候切一个环境变量就能切换配置，清晰又安全。

第三，static和media分开。static放的是项目自带的静态资源，比如CSS、JS、图片；media放的是用户运行时上传的文件，比如Excel导入的临时文件、员工头像。两者混在一起会出问题，因为部署时static通常交给Nginx直接服务，而media可能需要额外的权限控制和定期清理。

第四，templates按app分组。Django查找模板时，默认会遍历每个app下的templates目录。不推荐把模板全部扔到根目录下的templates里，那样文件多了会乱。按app分组的做法是templates/employees/employee_list.html，这样复用和维护都好办。

2.2 员工模块核心代码实现拆解

员工模块是整个系统中最核心的部分，围绕员工信息的增删改查展开。这里我挑几个有代表性的功能点来拆解。

先说员工列表页。列表页不只是简单查全表，通常需要支持分页、搜索、按部门筛选、按状态筛选。实现逻辑在视图里，核心代码如下：

from django.shortcuts import render from django.core.paginator import Paginator from .models import Employee def employee_list(request): # 基础查询集，select_related优化外键查询 queryset = Employee.objects.select_related('department').all() # 搜索 keyword = request.GET.get('keyword', '') if keyword: queryset = queryset.filter( models.Q(name__icontains=keyword) | models.Q(emp_id__icontains=keyword) ) # 筛选 department_id = request.GET.get('department', '') status = request.GET.get('status', '') if department_id: queryset = queryset.filter(department_id=department_id) if status: queryset = queryset.filter(status=status) # 分页 paginator = Paginator(queryset, 10) page_number = request.GET.get('page') page_obj = paginator.get_page(page_number) context = { 'page_obj': page_obj, 'keyword': keyword, 'department_id': department_id, 'status': status, } return render(request, 'employees/employee_list.html', context)

这里有两个细节是大部分模板代码里不会讲的。

第一个是select_related。如果员工表的department外键不加这个，翻页到每一行的时候，Django ORM都会额外查一次部门表，这就是N+1查询问题。数据处理量小的时候感觉不到，但几千条数据时，页面会明显变慢。加上select_related之后，Django会通过JOIN一次性把部门数据查出来，这是性能优化的基本功。

第二个是Q对象做关键字搜索。用Q可以把多个搜索条件用|连接，实现“名称或工号模糊匹配”的效果。如果不加Q，而是写两个filter，那搜索逻辑就变成“同时匹配名称和工号”，而不是“匹配名称或工号”，功能直接就不对了。

再说新增和编辑员工。Django有Form和ModelForm两种方式，推荐用ModelForm，因为它可以根据模型定义自动生成表单，还能利用模型里定义的校验规则。代码是这样的：

from django import forms from .models import Employee class EmployeeForm(forms.ModelForm): class Meta: model = Employee fields = ['emp_id', 'name', 'gender', 'birthday', 'phone', 'email', 'department', 'position', 'hire_date', 'status'] widgets = { 'birthday': forms.DateInput(attrs={'type': 'date'}), 'hire_date': forms.DateInput(attrs={'type': 'date'}), }

视图里处理表单提交的逻辑也值得说说。Django处理表单有一套固定流程，本质上是处理两种请求：GET请求返回空表单，POST请求校验数据。校验通过则保存，不通过则返回错误信息给用户。这段代码如果展开讲，是新手的第一个坎，因为很多人写表单总是忘了处理校验失败时数据回显的场景。ModelForm自动帮你做了这件事，错误信息和用户填过的数据都会存到表单对象里，模板里直接遍历表单字段就能回显。

2.3 认证与权限控制的代码细节

员工管理系统虽然内部使用，但也必须有登录认证和权限控制。Django自带的auth模块已经覆盖了大部分需求，不需要自己造轮子。

先看登录功能。Django提供了authenticate和login方法，逻辑很简单：验证用户名密码是否匹配，匹配则写入session。

from django.contrib.auth import authenticate, login from django.shortcuts import render, redirect def user_login(request): if request.method == 'POST': username = request.POST.get('username') password = request.POST.get('password') user = authenticate(request, username=username, password=password) if user is not None: login(request, user) return redirect('employee_list') else: error = '用户名或密码错误' return render(request, 'users/login.html', {'error': error}) return render(request, 'users/login.html')

登录之后，要对视图做访问控制。最基础的是加@login_required装饰器，未登录用户会跳转到登录页。

from django.contrib.auth.decorators import login_required @login_required def employee_list(request): ...

但光有登录控制还不够，员工管理系统通常还需要区分“管理员”和“普通HR”两种角色。管理员能删除数据，普通HR只能查看和编辑。这时候就要用到Django的Group和Permission机制。

Django的Permission分为add_employee、change_employee、delete_employee、view_employee，这是模型自动生成的四个基础权限。在Admin后台里创建两个组——管理员组和HR组，给HR组分配增、改、查权限，不给删除权限；管理员组则四个权限全给。然后在视图里用@permission_required装饰器来限制删除操作：

from django.contrib.auth.decorators import permission_required @permission_required('employees.delete_employee') def employee_delete(request, pk): ...

这里的employees是app的label，delete_employee是权限名。这样，即使普通HR能猜到删除接口的URL，直接访问也会被Django拦截并返回403页面。

权限控制的坑主要有一个：很多人在视图里自己写request.user.is_superuser判断，而不是用Django的权限系统。这会导致一旦需求变成“某个组的用户也可以删除”，就要改多处判断代码。用permission_required配合Group权限管理，后续加角色、调权限只需要在Admin后台操作，不用动代码。

3. 部署文档的编写与生产环境落地

3.1 本地开发环境搭建：Python虚拟环境与依赖管理

拿到项目源码后，第一步一定是先跑通本地环境。很多人的项目死在了环境搭建这一步，所以一个好的部署文档，一定要把环境搭建写得像菜谱一样清楚。

Python版本建议直接用3.10或3.11，Django版本推荐4.x LTS版本。虚拟环境是必须的，我见过太多人因为把不同项目的依赖装到了同一个Python环境里，最后版本冲突到崩溃。

# 创建虚拟环境 python -m venv venv # 激活虚拟环境（Windows） venv\Scripts\activate # 激活虚拟环境（Linux/Mac） source venv/bin/activate # 安装依赖 pip install -r requirements.txt

requirements.txt里至少要包含这些依赖：

Django==4.2.16 Pillow==10.4.0 waitress==3.0.0

其中Pillow是用来处理图片的，如果员工模块里有上传头像功能就必须装。waitress是Windows环境下常用的生产级WSGI服务器，后面部署章节会专门讲。

3.2 数据库迁移与初始化数据

环境装好后，接下来是数据库迁移。Django通过migrations机制管理数据库结构，任何模型的改动最终都会映射为migrations文件。执行迁移是部署新项目时最容易卡住的步骤，因为顺序错了就会报错一堆。

正确顺序是这样的：

# 1. 根据模型生成迁移文件 python manage.py makemigrations # 2. 执行迁移，真正创建表 python manage.py migrate # 3. 创建超级管理员账号 python manage.py createsuperuser # 4. 启动开发服务器 python manage.py runserver

这里有几个坑要提醒一下。

第一个是makemigrations之前一定要检查模型定义。如果模型定义了外键指向某张表，那外键指向的表必须先建好，否则Django会提示依赖错误。所以在多app的项目里，建议先迁移被依赖的app，或者直接在根目录下执行一次makemigrations，Django会自动分析依赖关系按顺序生成。

第二个是开发环境和生产环境的数据库选择。开发环境用默认的SQLite完全够用，文件型数据库，零配置，适合本地调试。但生产环境建议切换到MySQL或PostgreSQL。切换数据库不只是改settings里的配置，还要注意字段兼容性。比如SQLite里BooleanField存的是0/1，MySQL里是tinyint，虽然Django ORM自动做了转义，但如果你要手写SQL，这些差异就很折磨。所以部署文档里一定要写清楚：开发环境用什么数据库，生产环境用什么数据库，以及迁移工具需要什么前置条件。

第三个是初始化数据。系统没有数据，员工列表空空如也，很多功能没法验证。建议在项目里写一个初始化数据的脚本，用manage.py的shell命令或者数据迁移在数据库中初始化一些部门和测试员工。

python manage.py shell

from apps.departments.models import Department # 先初始化部门 tech_dept, _ = Department.objects.get_or_create( name='技术部', code='TECH' ) hr_dept, _ = Department.objects.get_or_create( name='人事部', code='HR' )

“get_or_create”比“create”好用，因为它能保证脚本可以重复执行，数据存在时不会因为创建重名而报错。

3.3 Windows环境：Python + Django + Waitress + Nginx

部署这个环节，我先从Windows讲起，因为很多做课程设计和内部系统的人，手头就是一台Windows服务器，没有Linux机器。而且热词里就有“python django windows10 waitress+nginx部署”这条，说明很多人确实卡在这上面。

先解释一下为什么要用Waitress。Django自带的runserver是开发服务器，它有一个致命问题：并发能力弱且不稳定，而且Django官方文档明确说runserver不能用在生产环境。在Windows上，WSGI服务器的选择很少，gunicorn不支持Windows（永远别在Windows上写gunicorn，它会直接报错或者进程起不起来），所以Waitress是Windows上生产部署Django的标准选择。

Waitress的使用非常简单：

pip install waitress

启动命令：

waitress-serve --listen=0.0.0.0:8000 config.wsgi:application

或者写一个启动脚本start.bat，方便一键启动：

@echo off cd /d %~dp0 call venv\Scripts\activate.bat waitress-serve --listen=0.0.0.0:8000 config.wsgi:application

Waitress监听0.0.0.0:8000之后，服务就在8000端口跑起来了。这时候问题来了：直接访问http://服务器IP:8000，用户是能访问，但有一个很尴尬的情况——如果你还需要对外提供80端口访问，或者要配HTTPS证书，就需要一个反向代理服务器。

这里的关键点是：Waitress本身只负责跑Django应用，它不擅长处理静态文件和HTTPS。所以用Nginx做反向代理，把动态请求转发给Waitress，把静态文件直接交给Nginx服务，既能分流压力，又能让Django项目以标准的80端口对外提供访问。

Nginx的配置片段如下：

server { listen 80; server_name your_domain.com; # 静态文件 location /static/ { alias C:/path/to/your_project/static/; } # 媒体文件 location /media/ { alias C:/path/to/your_project/media/; } # 动态请求转发给Waitress location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }

Nginx配置的注意事项：

静态文件的alias路径千万别写错。很多人配置好了Nginx，页面也能打开，但CSS、JS全部丢失，页面“裸奔”，十有八九就是alias路径写错了，或者路径末尾的斜杠没加对。建议配完之后，先直接访问一个静态文件URL验证，比如手动输入http://域名/static/admin/css/base.css，看能否正常返回文件内容。

还有proxy_set_header三个参数建议都写上。如果不写Host头，Django的request.get_host()会拿到本机上Nginx转发时的地址，而不是用户访问的域名。这会影响Django的CSRF校验、分页链接生成、以及某些绝对URL的拼接。

3.4 Linux部署方案与静态文件收集

Linux服务器是生产环境的常态，系统性的部署方案很成熟。与Windows类似，Linux上也可以走Nginx + WSGI服务器的方式，区别主要在WSGI服务器的选择上。

Linux上主流的Django WSGI服务器是Gunicorn，它是纯Python实现的，性能稳定，配置简单。

pip install gunicorn # 启动Django服务，绑定到本地8000端口 gunicorn config.wsgi:application --bind 127.0.0.1:8000 --workers 3

workers数量一般是CPU核数的2倍+1，不要盲目调大。worker太多会导致内存不足，太少则无法充分利用CPU。我一般用--workers 3起步，具体数值根据服务器配置调整。

Gunicorn启动后，同样用Nginx反向代理，配置和Windows下的写法基本一致，唯一区别是静态文件的路径要改成Linux目录。

还有一个Linux部署时的高频坑——静态文件收集。开发环境里，Django会自己处理静态文件，但生产环境设置DEBUG=False之后，Django不会自动服务静态文件，页面打开全是样式丢失。解决办法是在部署前执行：

python manage.py collectstatic

然后确认settings里配置好了STATIC_ROOT。实际操作中，collectstatic会把每个app的static目录以及你自定义的static目录里的文件全部拷贝到STATIC_ROOT指定的目录中。这个动作在部署文档里必须写明，漏掉它，用户名密码框显示正常，但页面样式全是乱的。

如果有需要定时执行的任务，比如每天早上更新员工考勤状态，可以用Linux的crontab，或者Supervisor来管理。这里不展开太多，但部署文档里至少要提一句“如何保证Django服务宕机后自动重启”——推荐用Supervisor，它会监控Gunicorn进程，挂了自动拉起来。

4. 常见问题与排查技巧实录

4.1 数据库迁移报错的排查

Django项目部署过程中，数据库迁移是报错重灾区。最典型的报错就是No migrations to apply。很多人执行migrate时看到这个提示一脸懵，但原因很简单：Django已经在django_migrations表里记录了这些迁移文件已经执行过，所以不会重复执行。常见场景是你手动删了数据库里的表，或者改了migrations文件名，导致Django认为迁移已经完成。

更常见的是模型字段改动后的迁移冲突。比如你已经执行了migrate生成了表，然后去models.py里给某个字段加了null=True，再执行makemigrations，Django会生成一个AlterField操作。如果数据库里这个字段有非空约束，而这个字段恰好又有NULL值，AlterField就会报错。解决方法是先清理数据，或者把字段统一成一个默认值再迁移。

我遇到最多的迁移报错是自己改了模型的related_name或者外键关系，导致Django生成的迁移文件里既有DeleteField又有AddField，一旦执行到一半数据库就锁卡住了。这种情况建议先不要急着逐条执行迁移，而是用python manage.py showmigrations看一下哪些迁移还没执行，逐层排查。

4.2 静态文件404问题

静态文件404是Django项目里最常见的页面“裸奔”问题，而且在本地开发和生产环境都会出现。

本地开发时，如果你使用runserver，但它不去处理static目录里的文件，通常是因为模板里加载静态文件时用了错误的引用方式。正确的加载方式是模板开头写{% load static %}，然后用{% static 'css/style.css' %}来生成静态文件URL。很多人直接写href="/static/css/style.css"，在没有配置STATICFILES_DIRS的时候，这种写法在本地勉强能跑，但迁移到生产环境稍有不慎就404。

生产环境里，DEBUG=False后Django彻底不处理静态文件，全交给Nginx或Whitenoise。我在项目里测试过，如果项目里用了Django Admin，生产部署时一定不能漏了Admin的静态文件。Admin的静态文件在Django安装目录下的contrib/admin/static里，执行collectstatic时会自动收集，但前提是你的STATIC_ROOT路径对collectstatic有写入权限。

4.3 时区与中文乱码问题

时区问题很容易被忽略，但它影响的都是一些很隐蔽的bug。Django默认的TIME_ZONE是UTC，USE_TZ是True。如果用户在中国时区操作，你往数据库里存一个“当前时间”，实际上存的是UTC时间。当你把创建时间显示到页面上时，如果模板没有做时区转换，就会比北京时间慢8个小时。

解决方案是在settings里配置成中国时区：

TIME_ZONE = 'Asia/Shanghai' USE_TZ = False

这里要注意一个历史包袱：老项目为了简化，直接设置USE_TZ = False，表示“不启用时区支持”，Django就会用本地时间存数据库。如果你的项目只需要在中国使用，这样做最简单。但如果将来业务拓展到其他时区，再改成USE_TZ = True做迁移会很痛苦。我的建议是新项目直接USE_TZ = True，配合TIME_ZONE = 'Asia/Shanghai'，然后在模板渲染时Django会自动把UTC时间转成上海时区展示。

中文乱码问题也很经典。Django 4.x默认数据库字符集是utf8mb4，基本不会出现乱码。但如果你用的是MySQL且建库时指定了latin1，那中文必然是乱码。解决方法是重建数据库，指定utf8mb4字符集和utf8mb4_general_ci排序规则。这一点放到部署文档里最合适，因为很多人辛辛苦苦部署完，打开页面中文全变问号，就是数据库字符集没配对。

4.4 CSRF校验失败与表单提交问题

CSRF校验失败是Django表单提交时的高频报错。报错信息通常是“CSRF token missing or incorrect”。出现这种情况，大多数原因是模板里的form表单忘记加了{% csrf_token %}标签。

但还有另一种隐蔽的情况：你加了{% csrf_token %}，但还是报CSRF错误。这通常是因为你用了跨域请求，或者Nginx反向代理时没有正确传Host头。我之前部署时遇到过，Nginx转发请求时，Django拿到的Host是127.0.0.1:8000，而用户的session是绑定在原始域名下的，导致CSRF token验证时参考的站点不匹配。解决方式就是在Nginx配置里加上proxy_set_header Host $host;，让Django看到正确的Host头。

另外，如果你在开发API接口，用Postman等工具测试POST请求，也要手动从cookie中提取CSRF token并放到请求头里，否则同样会报CSRF错误。

4.5 常见问题速查表

这个速查表建议写进项目部署文档里，省得别人遇到问题时到处翻文档。

5. 源码文档与代码讲解的编写心得

很多项目给到别人的时候，代码是完整的，但阅读体验很差。源码文档和代码讲解的质量，直接影响别人能不能快速上手。我在学习和带项目时总结了一些比较实用的写法，分享一下。

5.1 README要写什么

一个好的README应该是“别人拿到手就能把项目跑起来”的说明书，而不只是一堆介绍。最基本的，README要包含项目简介、环境要求、快速开始、目录结构说明、功能模块清单。

环境要求要写清楚Python版本、Django版本、数据库版本。我见过太多人README里没写Python版本，结果用Python 2的语法去跑Python 3项目，直接报语法错误。

快速开始部分要尽量简洁，让人复制粘贴就能跑。命令用代码块标注，并注明Windows和Linux的命令差异。

目录结构说明可以画一个简单的树状图，配上每个目录的文字说明，这会大大降低阅读源码的门槛。

5.2 部署文档怎么组织

部署文档最怕写成流水账，每一句都模棱两可。我的经验是把部署文档分成三个子文档：开发环境部署、生产环境部署、常见问题。三个文档各司其职，读者可以根据自己当前所处的阶段读取相关内容。

生产环境部署文档要有明确的步骤编号，并从零开始。很多人写部署文档默认读者什么都知道，但其实拿到部署文档的人，往往是最陌生的那个。所以每一步尽量写出预期的结果——执行完这一步，你应该能看到什么现象。比如“执行migrate后，你会看到Applying xx.0001_initial... OK”，这样读者能确认自己的操作是否正确。

5.3 代码讲解的讲解路径

代码讲解不能从views.py开始讲，那样听众和读者没有全局视角。我的习惯是按下述这个顺序讲解：

先讲项目路由入口，让读者知道一个URL是怎么进到某个视图的。再讲数据模型，这是系统的数据结构，也是最基础的部分。然后讲表单和视图，因为表单负责接收数据，视图负责处理数据。最后讲模板渲染，把数据展示到页面上。

这种路径是从“请求生命周期”的角度切入的，读者理解起来最自然。讲解时可以配合一个核心场景，比如“新增一个员工”，从用户填写表单到最终保存数据库，把整个链路的代码串起来讲一遍。这样读者不仅有代码层面的认知，也有业务层面的理解。

写在最后的几点体会

员工管理系统这个项目，说起来不算复杂，但它是一个能完整覆盖Django开发主线的经典项目。我从这个项目里学到的最重要的一点，不是某个框架API怎么用，而是“一个完整的软件交付物”应该包含什么——不只是能跑的代码，还有别人能看懂的文档、能复现的部署步骤、以及可能遇到的问题速查。

实际带过几个新人跑Django项目之后，我发现最容易卡住大家的往往不是业务逻辑本身，而是环境问题、路径问题、数据库问题这些“看起来不是技术问题”的地方。所以这个项目里，我会刻意把部署文档写得很详细，把静态文件、时区、CSRF这些坑都提前标注出来。帮别人省时间，也是在帮自己省时间。

最后再分享一个小技巧：给员工管理系统加一个“导出Excel”的功能，用openpyxl或者pandas实现都不难。这个功能在企业内部系统里太常用了。加了之后，你会发现你对“项目完整度”的理解又提升了一截——因为你会开始考虑编码格式、表头合并、数据校验这些真实业务里才有的细节，而这些东西，恰恰是代码讲解里最值得讲的内容。