django-mptt 是专为树形结构优化的第三方库，采用MPTT算法通过lft/rght/level字段避免递归查询；相比自关联Model，它解决N+1查询、跨数据库兼容性差及事务安全等问题。
django-mptt 是什么，为什么不用自关联 Model
它不是 Django 官方组件，而是一个成熟、稳定、专为树形结构优化的第三方库。核心价值在于用 MPTT（Modified Preorder Tree Traversal）算法把父子关系转成左右值（lft/rght）+ 层级（level）字段，避免递归查询。你如果只用 ForeignKey 自关联，查一个节点的全部祖先或子孙，要么 N+1 查询，要么写复杂 WITH RECURSIVE（PostgreSQL）或多次 JOIN（MySQL 不原生支持），性能和可维护性都差。
常见错误现象：RelatedObjectDoesNotExist 频发、列表页加载慢、后台批量移动节点时报 IntegrityError —— 这些往往不是代码逻辑错，而是没走 MPTT 的事务安全更新路径。
安装与基础模型定义必须做对这三步
别跳过迁移前的初始化步骤。装完 django-mptt 后，要在 settings.py 的 INSTALLED_APPS 里加 'mptt'；模型继承 MPTTModel，且必须显式声明 Meta.ordering = ['tree_id', 'lft']；最后运行 python manage.py migrate 之前，先执行 python manage.py mptt_register your_app.models.YourModel（Django ≥ 4.2 可省略，但老项目仍需）。
典型错误写法示例：
立即学习“Python免费学习笔记（深入）”；
class Category(MPTTModel):
name = models.CharField(max_length=100)
# ❌ 缺少 ordering，会导致 admin 排序错乱、get_children() 返回无序
# ❌ 没调 mptt_register（旧版）或没在 apps.py 中 ready() 里注册
- 字段名不能覆盖
lft、rght、tree_id、level，否则 MPTT 方法失效 - 新增字段建议加
blank=True, null=True，避免迁移时填默认值卡住 - 如果已有数据，用
python manage.py mptt_rebuild补全左右值，别手动 UPDATE
常用操作别硬写 SQL，直接用 MPTT 提供的方法
查子孙节点、移动子树、获取路径这些高频动作，MPTT 封装了原子化方法，比手写 filter(lft__gt=..., rght__lt=...) 更安全。比如 node.get_descendants(include_self=True) 返回的是 QuerySet，可链式调用 .select_related()；node.move_to(target, position='last-child') 会自动重算整棵子树的 lft/rght，且包裹在事务里。
容易被忽略的细节：
-
position参数只能是'first-child'、'last-child'、'left'、'right'，传'child'会静默失败 -
get_ancestors()默认不包含自己，要加include_self=True - 批量插入多个节点时，先用
model.objects.bulk_create()，再对每个调用.insert_at()，别试图一次 insert_at 多个 - 删除节点用
.delete()即可，MPTT 会自动收缩空隙，不需要手动 update 其他节点
模板中递归渲染要注意 depth 控制和缓存边界
Django 模板里用 {% load mptt_tags %} + {% recursetree nodes %} 最省事，但它默认不限制递归深度，遇到坏数据（比如环形引用）会栈溢出。务必配合 max_depth 参数：{% recursetree nodes max_depth=3 %}。
性能隐患点：
- 如果节点带外键（如
author），recursetree会为每个节点单独查一次，应提前用prefetch_related('author')或select_related('author') - 前端需要展开/折叠交互时，别一次性渲染全部层级，用 AJAX 按需加载子节点更稳妥
- 管理后台显示树形列表，记得在
ModelAdmin里加mptt_admin.MPTTModelAdmin，否则拖拽排序无效
真实项目里最常卡住的地方：迁移历史数据后忘了跑 mptt_rebuild，或者在信号（post_save）里调用了 move_to() 却没处理事务嵌套，导致部分节点 lft/rght 错位。这种问题不会报错，但树形遍历结果会漏节点或重复。
