说实话部门管理页面是我见过最容易被低估的全栈练手项目。看着就一张列表加几个表单真做起来模型设计、树形结构、权限控制全都要碰一遍。最近恰好帮团队把内部组织结构搬到线上用 Django 从零搭了一套部门管理页面整个过程走完后我最大的感觉是入门全栈与其跟着教程抄电商项目不如先搞定一个可以真实上线的组织架构模块。这篇文章就把项目从设计、建模、写功能到排查问题的完整过程整理出来。如果你正在学 Django或需要在公司里快速搭一个部门管理工具照着这份实操笔记走能少踩不少坑。1. 项目整体设计先想清楚再动手1.1 需求拆解部门管理页面到底要做什么先把需求收敛清楚。部门管理页面的核心需求其实就四件事看列表、加部门、改部门、删部门。但一旦放到真实业务里事情会变多部门要有层级比如总公司下面有研发部、市场部研发部下面又有前端组、后端组部门要有负责人和联系电话方便内部找人页面要能搜索部门多了不能靠人工滚动查找还得防误删尤其是上级部门下面挂着下级部门的时候。所以我第一版就拒绝做一个只有一张数据表格的 demo而是按真实场景设计部门模型支持无限层级列表可以展开显示父子关系新增和编辑用同一个表单模板删除操作给出提醒再套一层简单的登录限制。这才叫管理页面不是玩具。1.2 为什么选 Django 做全栈选 Django 做这个项目不是因为“流行”而是因为它的设计哲学跟管理后台类需求太契合了。Django 是 MVT 架构Model 管数据、View 管业务逻辑、Template 管页面展示一条请求的流转路径非常清晰浏览器发请求路由找到视图函数视图操作模型取数据再把数据渲染到模板返回页面。用它写 CRUD项目结构天然规整。和 Flask 对比的话Flask 轻巧灵活适合做 API 或小服务但要做好一个完整的管理页面你需要自己折腾 ORM、表单校验、分页、登录、后台管理这些 Django 全部内置了。省下来的时间可以专心处理业务本身。对全栈初学者来说Django 的约束反而是一种保护不容易把代码写飞。1.3 技术方案选型版本、数据库和前端我用的组合是Django 4.2 LTS、Python 3.11、SQLite开发阶段默认数据库、Bootstrap 5通过 CDN 引入、原生模板语言。没有引入任何前端框架和复杂脚手架。Django 版本建议直接用 LTS长期支持版4.2 到 2026 年 4 月前都有官方安全维护项目能安稳用很久。SQLite 作为开发库几乎没有配置成本等真正部署到 Linux 服务器时再按官方文档切 PostgreSQL改个数据库配置加个依赖就行。前端用 Bootstrap 是因为目标页面是后台工具美观不是第一位稳定、快速、对齐整齐才是重点它的栅格和表单样式足够用了。选项选择理由Python3.11Django 4.2 完全兼容类型提示体验好Django4.2 LTS长期维护文档全生态稳定数据库SQLite开发零配置后续可平滑切换 PostgreSQL前端Bootstrap 5后台页面重排版CDN 引入省打包流程2. 环境准备与项目初始化2.1 本地环境搭建虚拟环境不是可选项这一步看起来简单但我见过不少新手直接 pip install django 装到全局环境后面装了一堆包之后依赖冲突项目一跑就炸。正确的做法是给每个项目单独开虚拟环境。macOS/Linux 下是mkdir django-department cd django-department python3 -m venv venv source venv/bin/activate pip install django python -m django --versionWindows 下激活命令是venv\Scripts\activate。激活后命令行前缀会变成(venv)说明当前已经在独立环境里。为什么要这么做因为 Python 项目的依赖版本互相影响很常见虚拟环境把每一个项目的依赖隔离在各自目录中这才是符合工程习惯的做法。另外不要图省事用太旧的 PythonDjango 4.2 要求 Python 3.8 以上我建议直接 3.10 及以上。实测下来 Python 3.11 配 Django 4.2 非常稳定。2.2 创建项目与应用一条命令背后的目录结构环境准备好之后创建项目和应用django-admin startproject config . python manage.py startapp department python manage.py runserver这里有个细节值得讲startproject config .最后一个点不能漏。这个点表示在当前目录创建项目配置文件而不是再嵌套一层目录。加了点之后 manage.py 直接出现在项目根目录跑起来更清爽。startapp department会生成一个 department 目录里面有 models.py、views.py、admin.py、migrations 等文件。一个 Django 项目由多个 app 组成如果你后面要加用户模块、考勤模块每个都是独立 app这样代码按业务边界拆分不会出现所有逻辑都堆在一个 super_app 里的噩梦。创建完后记得在config/settings.py的 INSTALLED_APPS 里注册 department不注册的话数据库建表和 URL 匹配都会找不到你写的模型。这是一个非常容易漏、漏了报错还很隐晦的位置。2.3 整体开发路线图我用的是这条推进顺序我个人的开发顺序是这样的参考价值比较大先把数据模型写好并跑通迁移再注册 Admin 后台做快速数据维护然后写自定义列表页和表单页最后完善权限和部署。先用 Admin 而不是直接写页面是因为 Admin 能帮你快速确认模型字段和关联关系设计得对不对不用等页面搭完才发现外键关联错了白白返工。整体流程建 app、配置 settings定义 Department 模型跑迁移注册 admin录入测试部门数据写 department_list 视图 模板写 department_add / department_edit / department_delete加登录保护和页面统一布局关闭 DEBUG部署测试这个顺序能保证每一步都有可运行的结果不会有太久看不到页面的时候。3. 数据库模型设计部门树状结构的核心3.1 字段设计一张部门表需要哪些字段部门表最核心的字段就几个名称name、编码code、上级部门parent、负责人leader、联系电话phone、创建时间create_time、修改时间update_time。from django.db import models class Department(models.Model): name models.CharField(部门名称, max_length50, uniqueTrue) code models.CharField(部门编码, max_length20, uniqueTrue) parent models.ForeignKey( self, verbose_name上级部门, nullTrue, blankTrue, on_deletemodels.CASCADE, related_namechildren ) leader models.CharField(负责人, max_length20, blankTrue) phone models.CharField(联系电话, max_length20, blankTrue) create_time models.DateTimeField(创建时间, auto_now_addTrue) update_time models.DateTimeField(更新时间, auto_nowTrue) class Meta: ordering [code] verbose_name 部门 verbose_name_plural 部门 def __str__(self): return self.name字段设计的几个关键选择逐一说明。uniqueTrue 保证了名称和编码不重复这是部门管理的基本要求——你肯定不想出现两个“研发部”。parent 用 ForeignKey 指向自身允许为空空表示顶级部门。on_delete 设置为 CASCADE表示上级部门删除时下级一并删除这一点后面会专门讲它的风险。我特意加了 code 字段而不是只用 name 做主标识。原因是部门名称可能改研发部改名成技术研发中心但部门编码通常不变它更稳定适合用来做排序、同步甚至对接外部系统的唯一键。3.2 自关联外键树形结构的核心原理parent 是指向自己的外键这里面最关键的一句话是一张表里同时存了一条树的边。每一行部门记录都通过 parent 指向自己的上一级顶级部门的 parent 是 NULL这样所有部门就组成了一棵以 NULL 为根、向下蔓延的树。读取层级的常规做法有两种。第一种是递归从根节点往下逐层查询代码直观但会产生大量查询这就是典型的 N1 问题——部门一多数据库很受伤。第二种是查询一次全部部门在内存中用 Python 构建父子关系树结构展示时 O(n) 完成这是我最推荐的方式。列表页同时拿到所有部门后构建这样的 dictdef build_tree(departments): tree [] children {} for dep in departments: children.setdefault(dep.parent_id, []).append(dep) def walk(parent_id, depth0): nodes children.get(parent_id, []) for node in nodes: tree.append((node, depth)) walk(node.id, depth 1) walk(None) return tree这个方法维护一个以父 id 为键的子部门字典从 None 开始递归每一层深度 1返回的列表每一项是 (部门对象, 层级深度)。在模板中就可以根据 depth 数值做缩进或加前缀符号比如用几个全角空格或者一个“└──”。3.3 迁移与后台注册让模型真正变成数据库表模型写好后执行python manage.py makemigrations department python manage.py migratemakemigrations 会生成一个迁移文件记录这次模型的变更migrate 才真正在数据库里建表。新手常犯的错误是只跑 migrate 不跑 makemigrations或者改了模型后忘了重新生成迁移结果数据库表和代码不一致报出 Unknown column 之类的错误。建议大家养成一个习惯改完模型立刻跑python manage.py makemigrations --check这是一个只检查是否有未生成迁移、不改动任何内容的命令CI 里也可以放一道。注册 Admin 后台很简单from django.contrib import admin from .models import Department admin.register(Department) class DepartmentAdmin(admin.ModelAdmin): list_display [name, code, parent, leader, phone] search_fields [name, code]注册完登录/admin就能在后台直接增删改查部门。这一步不是为了展示是为了在开发阶段快速造数据后面写页面时就有真实数据可看。4. 部门管理的 CRUD 实现完整的增删改查流程4.1 列表页分页、搜索和树形展示列表页我采用函数视图Function-Based View因为它逻辑简单一步步看得明白。核心逻辑三块搜索过滤、分页、树形排序。from django.shortcuts import render from django.core.paginator import Paginator from .models import Department def department_list(request): departments Department.objects.all() keyword request.GET.get(q, ).strip() if keyword: departments departments.filter(name__icontainskeyword) tree build_tree(departments) paginator Paginator(tree, 20) page_number request.GET.get(page, 1) page_obj paginator.get_page(page_number) return render(request, department/list.html, { page_obj: page_obj, keyword: keyword, })这里有个容易踩的坑分页对象应该建立在树构建之后。如果直接对原本的模型分页然后再构建树分页会把同一个部门的子节点截到上一页结构就乱了。所以代码里先 build_tree 再分页每次分页切的是“一条一条缩进好的行”。模板部分遍历 page_obj并显示层级{% for item in page_obj %} {% with depitem.0 depthitem.1 %} tr td span stylemargin-left: {{ depth }}px;{{ dep.name }}/span /td td{{ dep.code }}/td td{{ dep.leader }}/td td{{ dep.phone }}/td /tr {% endwith %} {% endfor %}缩进我直接用 style 控制 margin-left简单有效。搜索框和分页导航再往模板里一放一个可用的列表页就出来了。4.2 搜索过滤别把查询条件写死搜索这块要说的不多但细节值得注意name__icontainskeyword是大小写不敏感的包含匹配对中文没有影响但搜索英文时更友好。search_fields 在 Admin 里也会自动用来显示搜索框。如果你搜的是编码不是名称加一行| models.Q(code__icontainskeyword)就可以做多字段组合from django.db.models import Q departments departments.filter( Q(name__icontainskeyword) | Q(code__icontainskeyword) )注意keyword 为空时这个 filter 不要执行否则全表会被通配匹配扫一遍虽然数据量小感觉不出来但习惯一定要养成。上面代码我用 if keyword 判断了。4.3 新增和编辑复用同一个表单和模板新增和编辑的逻辑高度重合我不建议写两套直接用一个 ModelForm 一个视图函数处理两种场景。from django import forms from .models import Department class DepartmentForm(forms.ModelForm): class Meta: model Department fields [name, code, parent, leader, phone] widgets { name: forms.TextInput(attrs{class: form-control}), code: forms.TextInput(attrs{class: form-control}), parent: forms.Select(attrs{class: form-control}), leader: forms.TextInput(attrs{class: form-control}), phone: forms.TextInput(attrs{class: form-control}), }widgets 给每个字段加上 Bootstrap 的 form-control 样式类这样渲染出来的表单能直接用不用在模板里手写每个 input 的 class。视图函数通过判断有没有传 id 来决定是新增还是编辑from django.shortcuts import redirect, get_object_or_404 from .forms import DepartmentForm def department_edit(request, pkNone): if pk: department get_object_or_404(Department, pkpk) page_title 编辑部门 else: department Department() page_title 新增部门 if request.method POST: form DepartmentForm(request.POST, instancedepartment) if form.is_valid(): form.save() return redirect(department_list) else: form DepartmentForm(instancedepartment) return render(request, department/form.html, { form: form, page_title: page_title, })ModelForm 的好处是自动从模型读字段做校验必填字段、长度限制、unique 冲突这些都不用手写。is_valid() 返回 False 时模板里 form.errors 会自动带上错误信息用户能直接看到哪里填错了。表单页模板里必须放一个{% csrf_token %}这是 Django 的 CSRF 防护要求。不加的话 POST 请求会被拒绝报 403 错误这是新手必踩的坑之一。4.4 删除操作Django 查询与删除对象的正确姿势删除功能的正确写法加上校验和提醒。先看视图def department_delete(request, pk): if request.method POST: department get_object_or_404(Department, pkpk) department.delete() return redirect(department_list) return redirect(department_list)删除用 POST 请求而不是 GET 链接这是安全规范。原因很简单搜索引擎爬虫、预加载机制、甚至用户手滑点到链接都会发起 GETGET 就能删数据误删概率大大增加。用 POST 并且明确在页面上放“确认删除”按钮虽然多了点步骤但安全上的收益非常大。关于“django 执行查询 - 删除对象”很多人会混淆两种删除方式。第一是调用单个实例的 delete()上面代码就是这种第二是 Queryset 的 delete()比如Department.objects.filter(name临时部门).delete()它会一次性删除整批记录。两种方式都会返回一个元组形如(4, {department.Department: 3, department.User: 1})第一个数字是删除的总数第二个字典记录了按模型分组删了多少条。这在删除前做检查、删除后做日志时很有用。但真正让我改代码的是这个问题on_delete 模型里定义了 CASCADE删除上级部门时下级部门会一起被删光。业务里的人事页面上这种“级联连带”常常不是期望行为万一主管手一快删除事业部底下二十个小组全没了找都找不回来。我建议业务上改成“有下级部门时禁止删除”在视图里加一层校验if department.children.exists(): # 有下级部门不能直接删 messages.error(request, 该部门下还有下级部门请先处理下级部门) return redirect(department_list)这才是生产环境该有的删除逻辑。如果确实需要保留历史数据更稳妥的方案是软删除给模型加 is_active 字段删除时只把 is_active 置为 False查询时默认过滤掉。硬删除物理删除会让历史记录跟着丢报表、考勤、审批流如果引用了部门外键数据完整性会出大问题。4.5 页面统一和模板继承不写重复的前端代码页面要统一必须用模板继承。base.html 放公共头部、导航、底部和一个{% block content %}占位具体页面只需要重写 content 里的内容。!DOCTYPE html html langzh head meta charsetUTF-8 title{% block title %}部门管理{% endblock %}/title link hrefhttps://cdn.jsdelivr.net/npm/bootstrap5.3.0/dist/css/bootstrap.min.css relstylesheet /head body nav classnavbar navbar-expand-lg navbar-dark bg-dark div classcontainer a classnavbar-brand href{% url department_list %}组织架构管理/a /div /nav div classcontainer mt-4 {% block content %}{% endblock %} /div /body /html列表页继承 base{% extends base.html %} {% block content %} div classd-flex justify-content-between mb-3 h3部门列表/h3 a href{% url department_add %} classbtn btn-primary新增部门/a /div !-- 搜索框、表格、分页 -- {% endblock %}用 Bootstrap 的栅格和表格结构页面不花哨但在内部工具里够看了。模板继承让所有页面公共的部分只写一遍后面调整导航栏时改 base.html 一处就生效这个习惯比省几个标签重要得多。5. 权限控制与后台加速登录态和快速维护5.1 登录保护用 Django 自带的认证先挡一层部门管理页面属于内部工具不能所有人访问至少得登录。Django 自带用户体系和登录视图最省事的是在视图函数上加装饰器from django.contrib.auth.decorators import login_required login_required def department_list(request): ...然后在 settings.py 里设置 LOGIN_URLLOGIN_URL /accounts/login/没登录的用户访问部门列表会被重定向到登录页。登录表单不用自己造Django 自带的django.contrib.auth.views.LoginView就能渲染登录页你只需要提供一个模板。登录成功后框架会在浏览器的 cookie 里写入 sessionid后续请求都带着这个 cookie 识别用户身份不需要手动去设置 token——Django 的 session 机制已经把这件事封装好了。如果你做的是前后端分离、用 JWT 保持登录中间逻辑会不一样但当前这个页面是服务端渲染把 session/cookie 链路理清楚就够了。5.2 Admin 后台用 Django 自带后台做快速数据维护Django Admin 是免费附赠的管理后台很多内部工具不加权限控制直接用 Admin 就够了。上面注册了 DepartmentAdmin进入 /admin 就能看到部门表点进去可以增删改查。想让 Admin 更好用可以把常用配置加上。list_display 控制列表显示的列search_fields 控制搜索框能搜哪些字段list_filter 加一个按上级部门过滤的筛选器admin.register(Department) class DepartmentAdmin(admin.ModelAdmin): list_display [name, code, parent, leader, phone, update_time] search_fields [name, code] list_filter [parent]如果觉得原生 Admin 样式太朴素可以装django-unfold它是目前社区里比较火的 Admin 换皮方案提供侧边栏、现代表格样式和暗色主题装上之后不用改业务代码后台观感能上一个台阶。具体安装步骤官方文档都有这里不展开。不过要提醒一句Admin 适合内部少量用户直接维护数据不适合直接对业务用户开放业务页面还是要按第 4 部分的逻辑自己写。5.3 从后台到自定义页面的取舍哪些情况需要自己写既然 Admin 这么好用为什么还要自己写页面第一Admin 的布局是面向维护人员的字段一堆全堆在表单里业务用户容易犯晕第二Admin 没法和你的业务界面样式统一第三真实场景往往需要把写好的数据和其他模块联动比如部门列表旁边要有在职人数统计、组织架构图、甚至实时推送部门变更通知。这些都需要自定义页面。如果你的目标是快速给团队一个能用的工具那我的建议是先跑通 Admin再按需写几个自定义页面不要一上来就全部自研。等需求逐渐明确再一步步从 Admin 迁移到自定义视图这是性价比最高的路径。6. 实操中的常见问题与排查技巧6.1 报错速查表十个高频问题一次说清这块整理成表格方便你对照报错 / 现象常见原因解决办法Unknown column department.dep.name改了模型没做迁移数据库表结构旧执行 makemigrations migrateTemplateDoesNotExist模板目录配置不对或 INSTALLED_APPS 没注册 app检查 settings 的 DIRS 和注册信息CSRF token missing or incorrect表单里没加 {% csrf_token %}模板中补上403 ForbiddenCSRF 校验失败或权限不足检查 csrf 令牌与登录状态301 跳转一直回到列表页LOGIN_URL 配置成列表页自己登录后死循环检查登录 URL 和相关 redirect 位置中文显示为乱码页面编码或数据库连接未用 utf8mb4settings 中设置字符集编辑器统一 UTF-8IntegrityError: UNIQUE constraint failedname 或 code 重复唯一约束没通过表单校验时给用户提示不能直接抛 500查询结果为 None 再调用 childrenparent 为 null 时调用关系管理器先判空或确保用正确的查询链TimeZoneWarning 时间差Django 默认 UTC本地时间对不上settings 里设置 TIME_ZONE Asia/Shanghai, USE_TZ 按需分页参数 page 传非数字手输 ?pageabcPaginator.get_page 已经处理不会崩但要核实6.2 调试习惯用 shell 和日志快速定位排查问题时我最常用的工具不是 IDE 断点而是 Django 的 shell。在项目根目录跑python manage.py shell可以直接执行模型的增删改查配合一段脚本模拟用户的查询路径定位问题比频繁改代码重启服务快得多。比如你怀疑列表页树构建有问题在 shell 里创建两个上下级部门再调 build_tree 看输出from department.models import Department root Department.objects.create(name总公司, codeHQ) child Department.objects.create(name研发部, codeRD, parentroot) departments Department.objects.all() print(build_tree(departments))另一个习惯是在视图里临时加print(request.GET, request.user)看请求参数。别小看 print 调试页面报错时先把请求上下文打出来很多问题答案就在其中。6.3 部署上线关闭 DEBUG 只是开始开发完成要上线时第一步就是DEBUG False不做这一步直接暴露的是完整的错误堆栈和配置细节属于安全底线。然后要让 Django 项目跑在一个正式服务器环境里常见组合是 Nginx Gunicorn Django之前的 SQLite 数据库建议换成 PostgreSQL。静态文件也要处理。本地开发时 Django 自动帮你服务静态文件生产环境下不会必须执行python manage.py collectstatic把 CSS、JS、图片收集到一个目录再让 Nginx 直接服务。这一步遗漏的后果是页面样式全部丢失。我用 gunicorn 启动 Django 进程的命令大致是gunicorn config.wsgi:application --bind 0.0.0.0:8000关于重启服务和日志查看生产环境还有一堆细节但部门管理的核心功能已经在第 3、4 节全部覆盖部署只要按官方文档别抄错误博客就没大问题。最后分享一点个人经验。部门管理页面说实话不是高难度项目但它把全栈链路完整走了一遍从模型设计开始你会认真想字段够不够用写到删除按钮时你会琢磨误删怎么防跑到上线还要面对静态文件和数据库切换。这些小问题单独拎出来都不难连在一起正是全栈真正的门槛。如果手头有这个需求别急着去买现成系统先自己动手写一版——等你写出来你对于 Django 的实际掌握会比刷一个月教程都扎实。我个人最推荐的后续扩展方向是两个一个是给部门列表加上 WebSocket 推送让组织架构变更实时通知到前端页面另一个是导出 Excel 报表。都很有意思等下次有空我再专门写写。
Django部门管理页面实战：从零搭建组织架构全栈功能
说实话部门管理页面是我见过最容易被低估的全栈练手项目。看着就一张列表加几个表单真做起来模型设计、树形结构、权限控制全都要碰一遍。最近恰好帮团队把内部组织结构搬到线上用 Django 从零搭了一套部门管理页面整个过程走完后我最大的感觉是入门全栈与其跟着教程抄电商项目不如先搞定一个可以真实上线的组织架构模块。这篇文章就把项目从设计、建模、写功能到排查问题的完整过程整理出来。如果你正在学 Django或需要在公司里快速搭一个部门管理工具照着这份实操笔记走能少踩不少坑。1. 项目整体设计先想清楚再动手1.1 需求拆解部门管理页面到底要做什么先把需求收敛清楚。部门管理页面的核心需求其实就四件事看列表、加部门、改部门、删部门。但一旦放到真实业务里事情会变多部门要有层级比如总公司下面有研发部、市场部研发部下面又有前端组、后端组部门要有负责人和联系电话方便内部找人页面要能搜索部门多了不能靠人工滚动查找还得防误删尤其是上级部门下面挂着下级部门的时候。所以我第一版就拒绝做一个只有一张数据表格的 demo而是按真实场景设计部门模型支持无限层级列表可以展开显示父子关系新增和编辑用同一个表单模板删除操作给出提醒再套一层简单的登录限制。这才叫管理页面不是玩具。1.2 为什么选 Django 做全栈选 Django 做这个项目不是因为“流行”而是因为它的设计哲学跟管理后台类需求太契合了。Django 是 MVT 架构Model 管数据、View 管业务逻辑、Template 管页面展示一条请求的流转路径非常清晰浏览器发请求路由找到视图函数视图操作模型取数据再把数据渲染到模板返回页面。用它写 CRUD项目结构天然规整。和 Flask 对比的话Flask 轻巧灵活适合做 API 或小服务但要做好一个完整的管理页面你需要自己折腾 ORM、表单校验、分页、登录、后台管理这些 Django 全部内置了。省下来的时间可以专心处理业务本身。对全栈初学者来说Django 的约束反而是一种保护不容易把代码写飞。1.3 技术方案选型版本、数据库和前端我用的组合是Django 4.2 LTS、Python 3.11、SQLite开发阶段默认数据库、Bootstrap 5通过 CDN 引入、原生模板语言。没有引入任何前端框架和复杂脚手架。Django 版本建议直接用 LTS长期支持版4.2 到 2026 年 4 月前都有官方安全维护项目能安稳用很久。SQLite 作为开发库几乎没有配置成本等真正部署到 Linux 服务器时再按官方文档切 PostgreSQL改个数据库配置加个依赖就行。前端用 Bootstrap 是因为目标页面是后台工具美观不是第一位稳定、快速、对齐整齐才是重点它的栅格和表单样式足够用了。选项选择理由Python3.11Django 4.2 完全兼容类型提示体验好Django4.2 LTS长期维护文档全生态稳定数据库SQLite开发零配置后续可平滑切换 PostgreSQL前端Bootstrap 5后台页面重排版CDN 引入省打包流程2. 环境准备与项目初始化2.1 本地环境搭建虚拟环境不是可选项这一步看起来简单但我见过不少新手直接 pip install django 装到全局环境后面装了一堆包之后依赖冲突项目一跑就炸。正确的做法是给每个项目单独开虚拟环境。macOS/Linux 下是mkdir django-department cd django-department python3 -m venv venv source venv/bin/activate pip install django python -m django --versionWindows 下激活命令是venv\Scripts\activate。激活后命令行前缀会变成(venv)说明当前已经在独立环境里。为什么要这么做因为 Python 项目的依赖版本互相影响很常见虚拟环境把每一个项目的依赖隔离在各自目录中这才是符合工程习惯的做法。另外不要图省事用太旧的 PythonDjango 4.2 要求 Python 3.8 以上我建议直接 3.10 及以上。实测下来 Python 3.11 配 Django 4.2 非常稳定。2.2 创建项目与应用一条命令背后的目录结构环境准备好之后创建项目和应用django-admin startproject config . python manage.py startapp department python manage.py runserver这里有个细节值得讲startproject config .最后一个点不能漏。这个点表示在当前目录创建项目配置文件而不是再嵌套一层目录。加了点之后 manage.py 直接出现在项目根目录跑起来更清爽。startapp department会生成一个 department 目录里面有 models.py、views.py、admin.py、migrations 等文件。一个 Django 项目由多个 app 组成如果你后面要加用户模块、考勤模块每个都是独立 app这样代码按业务边界拆分不会出现所有逻辑都堆在一个 super_app 里的噩梦。创建完后记得在config/settings.py的 INSTALLED_APPS 里注册 department不注册的话数据库建表和 URL 匹配都会找不到你写的模型。这是一个非常容易漏、漏了报错还很隐晦的位置。2.3 整体开发路线图我用的是这条推进顺序我个人的开发顺序是这样的参考价值比较大先把数据模型写好并跑通迁移再注册 Admin 后台做快速数据维护然后写自定义列表页和表单页最后完善权限和部署。先用 Admin 而不是直接写页面是因为 Admin 能帮你快速确认模型字段和关联关系设计得对不对不用等页面搭完才发现外键关联错了白白返工。整体流程建 app、配置 settings定义 Department 模型跑迁移注册 admin录入测试部门数据写 department_list 视图 模板写 department_add / department_edit / department_delete加登录保护和页面统一布局关闭 DEBUG部署测试这个顺序能保证每一步都有可运行的结果不会有太久看不到页面的时候。3. 数据库模型设计部门树状结构的核心3.1 字段设计一张部门表需要哪些字段部门表最核心的字段就几个名称name、编码code、上级部门parent、负责人leader、联系电话phone、创建时间create_time、修改时间update_time。from django.db import models class Department(models.Model): name models.CharField(部门名称, max_length50, uniqueTrue) code models.CharField(部门编码, max_length20, uniqueTrue) parent models.ForeignKey( self, verbose_name上级部门, nullTrue, blankTrue, on_deletemodels.CASCADE, related_namechildren ) leader models.CharField(负责人, max_length20, blankTrue) phone models.CharField(联系电话, max_length20, blankTrue) create_time models.DateTimeField(创建时间, auto_now_addTrue) update_time models.DateTimeField(更新时间, auto_nowTrue) class Meta: ordering [code] verbose_name 部门 verbose_name_plural 部门 def __str__(self): return self.name字段设计的几个关键选择逐一说明。uniqueTrue 保证了名称和编码不重复这是部门管理的基本要求——你肯定不想出现两个“研发部”。parent 用 ForeignKey 指向自身允许为空空表示顶级部门。on_delete 设置为 CASCADE表示上级部门删除时下级一并删除这一点后面会专门讲它的风险。我特意加了 code 字段而不是只用 name 做主标识。原因是部门名称可能改研发部改名成技术研发中心但部门编码通常不变它更稳定适合用来做排序、同步甚至对接外部系统的唯一键。3.2 自关联外键树形结构的核心原理parent 是指向自己的外键这里面最关键的一句话是一张表里同时存了一条树的边。每一行部门记录都通过 parent 指向自己的上一级顶级部门的 parent 是 NULL这样所有部门就组成了一棵以 NULL 为根、向下蔓延的树。读取层级的常规做法有两种。第一种是递归从根节点往下逐层查询代码直观但会产生大量查询这就是典型的 N1 问题——部门一多数据库很受伤。第二种是查询一次全部部门在内存中用 Python 构建父子关系树结构展示时 O(n) 完成这是我最推荐的方式。列表页同时拿到所有部门后构建这样的 dictdef build_tree(departments): tree [] children {} for dep in departments: children.setdefault(dep.parent_id, []).append(dep) def walk(parent_id, depth0): nodes children.get(parent_id, []) for node in nodes: tree.append((node, depth)) walk(node.id, depth 1) walk(None) return tree这个方法维护一个以父 id 为键的子部门字典从 None 开始递归每一层深度 1返回的列表每一项是 (部门对象, 层级深度)。在模板中就可以根据 depth 数值做缩进或加前缀符号比如用几个全角空格或者一个“└──”。3.3 迁移与后台注册让模型真正变成数据库表模型写好后执行python manage.py makemigrations department python manage.py migratemakemigrations 会生成一个迁移文件记录这次模型的变更migrate 才真正在数据库里建表。新手常犯的错误是只跑 migrate 不跑 makemigrations或者改了模型后忘了重新生成迁移结果数据库表和代码不一致报出 Unknown column 之类的错误。建议大家养成一个习惯改完模型立刻跑python manage.py makemigrations --check这是一个只检查是否有未生成迁移、不改动任何内容的命令CI 里也可以放一道。注册 Admin 后台很简单from django.contrib import admin from .models import Department admin.register(Department) class DepartmentAdmin(admin.ModelAdmin): list_display [name, code, parent, leader, phone] search_fields [name, code]注册完登录/admin就能在后台直接增删改查部门。这一步不是为了展示是为了在开发阶段快速造数据后面写页面时就有真实数据可看。4. 部门管理的 CRUD 实现完整的增删改查流程4.1 列表页分页、搜索和树形展示列表页我采用函数视图Function-Based View因为它逻辑简单一步步看得明白。核心逻辑三块搜索过滤、分页、树形排序。from django.shortcuts import render from django.core.paginator import Paginator from .models import Department def department_list(request): departments Department.objects.all() keyword request.GET.get(q, ).strip() if keyword: departments departments.filter(name__icontainskeyword) tree build_tree(departments) paginator Paginator(tree, 20) page_number request.GET.get(page, 1) page_obj paginator.get_page(page_number) return render(request, department/list.html, { page_obj: page_obj, keyword: keyword, })这里有个容易踩的坑分页对象应该建立在树构建之后。如果直接对原本的模型分页然后再构建树分页会把同一个部门的子节点截到上一页结构就乱了。所以代码里先 build_tree 再分页每次分页切的是“一条一条缩进好的行”。模板部分遍历 page_obj并显示层级{% for item in page_obj %} {% with depitem.0 depthitem.1 %} tr td span stylemargin-left: {{ depth }}px;{{ dep.name }}/span /td td{{ dep.code }}/td td{{ dep.leader }}/td td{{ dep.phone }}/td /tr {% endwith %} {% endfor %}缩进我直接用 style 控制 margin-left简单有效。搜索框和分页导航再往模板里一放一个可用的列表页就出来了。4.2 搜索过滤别把查询条件写死搜索这块要说的不多但细节值得注意name__icontainskeyword是大小写不敏感的包含匹配对中文没有影响但搜索英文时更友好。search_fields 在 Admin 里也会自动用来显示搜索框。如果你搜的是编码不是名称加一行| models.Q(code__icontainskeyword)就可以做多字段组合from django.db.models import Q departments departments.filter( Q(name__icontainskeyword) | Q(code__icontainskeyword) )注意keyword 为空时这个 filter 不要执行否则全表会被通配匹配扫一遍虽然数据量小感觉不出来但习惯一定要养成。上面代码我用 if keyword 判断了。4.3 新增和编辑复用同一个表单和模板新增和编辑的逻辑高度重合我不建议写两套直接用一个 ModelForm 一个视图函数处理两种场景。from django import forms from .models import Department class DepartmentForm(forms.ModelForm): class Meta: model Department fields [name, code, parent, leader, phone] widgets { name: forms.TextInput(attrs{class: form-control}), code: forms.TextInput(attrs{class: form-control}), parent: forms.Select(attrs{class: form-control}), leader: forms.TextInput(attrs{class: form-control}), phone: forms.TextInput(attrs{class: form-control}), }widgets 给每个字段加上 Bootstrap 的 form-control 样式类这样渲染出来的表单能直接用不用在模板里手写每个 input 的 class。视图函数通过判断有没有传 id 来决定是新增还是编辑from django.shortcuts import redirect, get_object_or_404 from .forms import DepartmentForm def department_edit(request, pkNone): if pk: department get_object_or_404(Department, pkpk) page_title 编辑部门 else: department Department() page_title 新增部门 if request.method POST: form DepartmentForm(request.POST, instancedepartment) if form.is_valid(): form.save() return redirect(department_list) else: form DepartmentForm(instancedepartment) return render(request, department/form.html, { form: form, page_title: page_title, })ModelForm 的好处是自动从模型读字段做校验必填字段、长度限制、unique 冲突这些都不用手写。is_valid() 返回 False 时模板里 form.errors 会自动带上错误信息用户能直接看到哪里填错了。表单页模板里必须放一个{% csrf_token %}这是 Django 的 CSRF 防护要求。不加的话 POST 请求会被拒绝报 403 错误这是新手必踩的坑之一。4.4 删除操作Django 查询与删除对象的正确姿势删除功能的正确写法加上校验和提醒。先看视图def department_delete(request, pk): if request.method POST: department get_object_or_404(Department, pkpk) department.delete() return redirect(department_list) return redirect(department_list)删除用 POST 请求而不是 GET 链接这是安全规范。原因很简单搜索引擎爬虫、预加载机制、甚至用户手滑点到链接都会发起 GETGET 就能删数据误删概率大大增加。用 POST 并且明确在页面上放“确认删除”按钮虽然多了点步骤但安全上的收益非常大。关于“django 执行查询 - 删除对象”很多人会混淆两种删除方式。第一是调用单个实例的 delete()上面代码就是这种第二是 Queryset 的 delete()比如Department.objects.filter(name临时部门).delete()它会一次性删除整批记录。两种方式都会返回一个元组形如(4, {department.Department: 3, department.User: 1})第一个数字是删除的总数第二个字典记录了按模型分组删了多少条。这在删除前做检查、删除后做日志时很有用。但真正让我改代码的是这个问题on_delete 模型里定义了 CASCADE删除上级部门时下级部门会一起被删光。业务里的人事页面上这种“级联连带”常常不是期望行为万一主管手一快删除事业部底下二十个小组全没了找都找不回来。我建议业务上改成“有下级部门时禁止删除”在视图里加一层校验if department.children.exists(): # 有下级部门不能直接删 messages.error(request, 该部门下还有下级部门请先处理下级部门) return redirect(department_list)这才是生产环境该有的删除逻辑。如果确实需要保留历史数据更稳妥的方案是软删除给模型加 is_active 字段删除时只把 is_active 置为 False查询时默认过滤掉。硬删除物理删除会让历史记录跟着丢报表、考勤、审批流如果引用了部门外键数据完整性会出大问题。4.5 页面统一和模板继承不写重复的前端代码页面要统一必须用模板继承。base.html 放公共头部、导航、底部和一个{% block content %}占位具体页面只需要重写 content 里的内容。!DOCTYPE html html langzh head meta charsetUTF-8 title{% block title %}部门管理{% endblock %}/title link hrefhttps://cdn.jsdelivr.net/npm/bootstrap5.3.0/dist/css/bootstrap.min.css relstylesheet /head body nav classnavbar navbar-expand-lg navbar-dark bg-dark div classcontainer a classnavbar-brand href{% url department_list %}组织架构管理/a /div /nav div classcontainer mt-4 {% block content %}{% endblock %} /div /body /html列表页继承 base{% extends base.html %} {% block content %} div classd-flex justify-content-between mb-3 h3部门列表/h3 a href{% url department_add %} classbtn btn-primary新增部门/a /div !-- 搜索框、表格、分页 -- {% endblock %}用 Bootstrap 的栅格和表格结构页面不花哨但在内部工具里够看了。模板继承让所有页面公共的部分只写一遍后面调整导航栏时改 base.html 一处就生效这个习惯比省几个标签重要得多。5. 权限控制与后台加速登录态和快速维护5.1 登录保护用 Django 自带的认证先挡一层部门管理页面属于内部工具不能所有人访问至少得登录。Django 自带用户体系和登录视图最省事的是在视图函数上加装饰器from django.contrib.auth.decorators import login_required login_required def department_list(request): ...然后在 settings.py 里设置 LOGIN_URLLOGIN_URL /accounts/login/没登录的用户访问部门列表会被重定向到登录页。登录表单不用自己造Django 自带的django.contrib.auth.views.LoginView就能渲染登录页你只需要提供一个模板。登录成功后框架会在浏览器的 cookie 里写入 sessionid后续请求都带着这个 cookie 识别用户身份不需要手动去设置 token——Django 的 session 机制已经把这件事封装好了。如果你做的是前后端分离、用 JWT 保持登录中间逻辑会不一样但当前这个页面是服务端渲染把 session/cookie 链路理清楚就够了。5.2 Admin 后台用 Django 自带后台做快速数据维护Django Admin 是免费附赠的管理后台很多内部工具不加权限控制直接用 Admin 就够了。上面注册了 DepartmentAdmin进入 /admin 就能看到部门表点进去可以增删改查。想让 Admin 更好用可以把常用配置加上。list_display 控制列表显示的列search_fields 控制搜索框能搜哪些字段list_filter 加一个按上级部门过滤的筛选器admin.register(Department) class DepartmentAdmin(admin.ModelAdmin): list_display [name, code, parent, leader, phone, update_time] search_fields [name, code] list_filter [parent]如果觉得原生 Admin 样式太朴素可以装django-unfold它是目前社区里比较火的 Admin 换皮方案提供侧边栏、现代表格样式和暗色主题装上之后不用改业务代码后台观感能上一个台阶。具体安装步骤官方文档都有这里不展开。不过要提醒一句Admin 适合内部少量用户直接维护数据不适合直接对业务用户开放业务页面还是要按第 4 部分的逻辑自己写。5.3 从后台到自定义页面的取舍哪些情况需要自己写既然 Admin 这么好用为什么还要自己写页面第一Admin 的布局是面向维护人员的字段一堆全堆在表单里业务用户容易犯晕第二Admin 没法和你的业务界面样式统一第三真实场景往往需要把写好的数据和其他模块联动比如部门列表旁边要有在职人数统计、组织架构图、甚至实时推送部门变更通知。这些都需要自定义页面。如果你的目标是快速给团队一个能用的工具那我的建议是先跑通 Admin再按需写几个自定义页面不要一上来就全部自研。等需求逐渐明确再一步步从 Admin 迁移到自定义视图这是性价比最高的路径。6. 实操中的常见问题与排查技巧6.1 报错速查表十个高频问题一次说清这块整理成表格方便你对照报错 / 现象常见原因解决办法Unknown column department.dep.name改了模型没做迁移数据库表结构旧执行 makemigrations migrateTemplateDoesNotExist模板目录配置不对或 INSTALLED_APPS 没注册 app检查 settings 的 DIRS 和注册信息CSRF token missing or incorrect表单里没加 {% csrf_token %}模板中补上403 ForbiddenCSRF 校验失败或权限不足检查 csrf 令牌与登录状态301 跳转一直回到列表页LOGIN_URL 配置成列表页自己登录后死循环检查登录 URL 和相关 redirect 位置中文显示为乱码页面编码或数据库连接未用 utf8mb4settings 中设置字符集编辑器统一 UTF-8IntegrityError: UNIQUE constraint failedname 或 code 重复唯一约束没通过表单校验时给用户提示不能直接抛 500查询结果为 None 再调用 childrenparent 为 null 时调用关系管理器先判空或确保用正确的查询链TimeZoneWarning 时间差Django 默认 UTC本地时间对不上settings 里设置 TIME_ZONE Asia/Shanghai, USE_TZ 按需分页参数 page 传非数字手输 ?pageabcPaginator.get_page 已经处理不会崩但要核实6.2 调试习惯用 shell 和日志快速定位排查问题时我最常用的工具不是 IDE 断点而是 Django 的 shell。在项目根目录跑python manage.py shell可以直接执行模型的增删改查配合一段脚本模拟用户的查询路径定位问题比频繁改代码重启服务快得多。比如你怀疑列表页树构建有问题在 shell 里创建两个上下级部门再调 build_tree 看输出from department.models import Department root Department.objects.create(name总公司, codeHQ) child Department.objects.create(name研发部, codeRD, parentroot) departments Department.objects.all() print(build_tree(departments))另一个习惯是在视图里临时加print(request.GET, request.user)看请求参数。别小看 print 调试页面报错时先把请求上下文打出来很多问题答案就在其中。6.3 部署上线关闭 DEBUG 只是开始开发完成要上线时第一步就是DEBUG False不做这一步直接暴露的是完整的错误堆栈和配置细节属于安全底线。然后要让 Django 项目跑在一个正式服务器环境里常见组合是 Nginx Gunicorn Django之前的 SQLite 数据库建议换成 PostgreSQL。静态文件也要处理。本地开发时 Django 自动帮你服务静态文件生产环境下不会必须执行python manage.py collectstatic把 CSS、JS、图片收集到一个目录再让 Nginx 直接服务。这一步遗漏的后果是页面样式全部丢失。我用 gunicorn 启动 Django 进程的命令大致是gunicorn config.wsgi:application --bind 0.0.0.0:8000关于重启服务和日志查看生产环境还有一堆细节但部门管理的核心功能已经在第 3、4 节全部覆盖部署只要按官方文档别抄错误博客就没大问题。最后分享一点个人经验。部门管理页面说实话不是高难度项目但它把全栈链路完整走了一遍从模型设计开始你会认真想字段够不够用写到删除按钮时你会琢磨误删怎么防跑到上线还要面对静态文件和数据库切换。这些小问题单独拎出来都不难连在一起正是全栈真正的门槛。如果手头有这个需求别急着去买现成系统先自己动手写一版——等你写出来你对于 Django 的实际掌握会比刷一个月教程都扎实。我个人最推荐的后续扩展方向是两个一个是给部门列表加上 WebSocket 推送让组织架构变更实时通知到前端页面另一个是导出 Excel 报表。都很有意思等下次有空我再专门写写。
