智汇笔记后端实战(三):三级目录树的实现与踩坑
〇、问题背景
任务书写得轻描淡写：Notebook 表必须支持至少 3 级的父子级嵌套目录关系设计。听起来很简单，但当我真正动手实现"创建 / 查整棵树 / 改名 / 移动 / 删除"5 个操作时，发现这是整个后端目前最容易翻车的模块。
我把这次踩到的 4 个核心问题挑出来讲，每个都对应代码里一段真实的判断逻辑。
一、第一个问题：树到底怎么存？
主流方案三个：
| 方案 | 写代价 | 查整棵子树 | 移动节点 | 适合场景 |
|---|---|---|---|---|
邻接表（parent_id） | O(1) | 朴素写法要查 N 次 | O(1) | 写多读少、深度浅 |
路径枚举（path = '/1/3/7/'） | O(h) | LIKE 一条 SQL | 整棵子树 path 重写 | 读多写少 |
闭包表 | O(h)，每个节点要插 h 行 | 一条 JOIN | 多行增删 | 查询极强、不怕写放大 |
我选了邻接表 + 冗余 depth 字段。理由很现实：
- 我的深度被任务书锁死了 ≤ 3，闭包表那种"为查询无限优化"的能力毫无收益；
- 用户会频繁重命名和移动目录，闭包表写放大不划算；
- MySQL 8 的递归 CTE 把"邻接表查不动整棵树"的传统痛点解决了，邻接表的最大短板被补齐。
但邻接表有个特别容易被忽略的小事：parent_id是用 NULL 还是 0 表示根？
我选0。原因：MySQL 索引对 NULL 的处理一向不友好，WHERE parent_id = ?在传 null 时还得改写成IS NULL，业务代码全是分支。统一用 0 后，所有 SQL 写法一致，前端拿到parentId === 0也立刻知道这是根节点——这是隐式契约，但确实减少了大量心智负担。
二、第二个问题：查整棵树，怎么避免 N+1？
我第一版差点这么写：
NotebookTreeVO root = ...;
fillChildren(root); // 内部递归调 mapper.listChildren()
void fillChildren(NotebookTreeVO node) {
List<Notebook> children = mapper.listChildren(uid, node.getId());
for (Notebook child : children) {
NotebookTreeVO childVO = toVO(child);
node.getChildren().add(childVO);
fillChildren(childVO); // 再递归
}
}
看起来对。但每展开一个节点就跑一次 SQL，深度 3、每层 5 个节点，最坏会跑 1 + 5 + 25 = 31 次查询。这是经典的 N+1 查询——单用户没事，并发 50 用户同时打开"工作台首页"就是个事故现场。
我换成一次 SQL 拉全量 + O(n) 内存组装：
public List<NotebookTreeVO> tree() {
Long uid = DataOwnershipAssert.currentUserIdOrThrow();
List<Notebook> all = notebookMapper.listAllByUser(uid);
// 1) 先建 id -> VO 索引（O(n)）
Map<Long, NotebookTreeVO> idIndex = new HashMap<>(all.size() * 2);
for (Notebook nb : all) {
idIndex.put(nb.getId(), toTreeVO(nb));
}
// 2) 再走一遍，按 parentId 挂到对应节点的 children 上（O(n)）
List<NotebookTreeVO> roots = new ArrayList<>();
for (Notebook nb : all) {
NotebookTreeVO node = idIndex.get(nb.getId());
if (Objects.equals(nb.getParentId(), Notebook.ROOT_PARENT_ID)) {
roots.add(node);
continue;
}
NotebookTreeVO parent = idIndex.get(nb.getParentId());
if (parent != null) {
parent.getChildren().add(node);
} else {
roots.add(node); // 兜底，理论上不应触发
}
}
return roots;
}
1 次查询往返 + O(n) 复杂度，深度 100、节点 1000 的极端情况都在 50ms 以内。任务书要求"响应 < 100ms"轻松达标。
这里有个细节：我特意idIndex里建的是Map<Long, NotebookTreeVO>而不是Map<Long, Notebook>——这样第二遍循环挂 children 的时候，挂的是已经准备好的 VO，不用再做一次toVO转换。这可以在节点数大时省掉一半对象分配。
三、第三个问题：移动节点，怎么避免成环？
这是我这周印象最深的一个 bug。
用户操作"把目录 A 拖到目录 P 下面"，正常情况没问题。但如果 P 本身就是 A 的子孙呢？
举个例子：
根 → 编程 → Java → Spring
如果用户作死把"编程"拖到"Spring"下面，数据会变成：
Spring → 编程 → Java → Spring ← 成环了
后续findDescendantIds的递归 CTE 会无限展开直到 MySQL 切断，整棵树的查询全部崩溃。
我的拦截逻辑：
// 环检测：新父节点不能在当前节点的子孙集合中
if (newParentId != Notebook.ROOT_PARENT_ID) {
List<Long> descendants = notebookMapper.findDescendantIds(uid, id);
if (descendants.contains(newParentId)) {
throw new BadRequestException("不能把目录移动到它自己的子目录下");
}
}
巧的是这正好复用了之前写的递归 CTE：
WITH RECURSIVE descendant AS (
SELECT id, parent_id FROM notebook WHERE id = #{rootId} AND user_id = #{userId} ...
UNION ALL
SELECT n.id, n.parent_id FROM notebook n INNER JOIN descendant d ON n.parent_id = d.id ...
)
SELECT id FROM descendant
之前写它是为了"级联软删"，没想到移动操作也直接受益。一段 SQL 撑两个完全不同的业务——这种复用感是我这周最爽的瞬间。
四、第四个问题：移动之后，子树的 depth 怎么办？
这是我最后才意识到的坑。
notebook表里我冗余存了depth字段，方便 O(1) 校验"不能超 3 级"。但移动节点时，子孙的 depth 也得跟着变——
举例：
- 移动前：根 (depth=1) → 编程 (depth=2) → Java (depth=3)
- 把"编程"移动到根级（parent=0），单独执行
move(编程, depth=1) - 此时 Java 的 depth 还是 3，但它现在的真实路径只有 2 级。数据不一致了。
下次校验"能不能在 Java 下面再建子目录"时，因为 Java.depth=3，校验逻辑会拒绝——而事实上根 (1) → 编程 (2) → Java (2，但旧值是3) 还有空间。
我加了一段shiftSubtreeDepth：
private void shiftSubtreeDepth(Long userId, Long rootId, int diff, LocalDateTime now) {
if (diff == 0) return;
List<Long> ids = notebookMapper.findDescendantIds(userId, rootId);
if (ids.size() <= 1) return;
for (Long childId : ids) {
if (Objects.equals(childId, rootId)) continue;
Notebook child = notebookMapper.findByIdAndUser(childId, userId);
if (child == null) continue;
notebookMapper.move(childId, userId,
child.getParentId(), child.getDepth() + diff,
child.getSort(), now);
}
}
把整棵子树 depth 同步偏移，diff 可以是正可以是负。
反思：冗余字段就像备份——一旦决定冗余，就得保证所有变更入口都同步刷新它，否则它就从"性能助攻"变成"数据炸弹"。我一开始没考虑到这一点，是测试时手动跑了 3 次移动操作之后才发现 depth 飘了。这个教训我在后续做 Note 表时就提前规避了——所以 Note 不冗余 depth。
五、补充：还有一个隐藏坑——移动后会撑破 3 级吗？
移动节点 A 到新父 P 后，A 的子孙最深叶能不能挺住 ≤ 3 级？
我加了一个子树相对深度的预判：
int newDepth = resolveChildDepth(uid, newParentId); // A 移动后的新深度
int subtreeDepth = computeSubtreeMaxRelativeDepth(uid, id); // A 子树最深叶的相对偏移
if (newDepth + subtreeDepth > Notebook.MAX_DEPTH) {
throw new BadRequestException(
"移动后会超过最大层级（" + Notebook.MAX_DEPTH + " 级），请先调整子目录结构");
}
逻辑是：A 自己是 1，叶节点最多比 A 深subtreeDepth层。把 A 挂到newDepth这个层级后，叶节点的绝对层级 =newDepth + subtreeDepth，不能超过 3。
这一行校验帮我兜住了三种用户操作错误：
- 把已经 3 级的子树拖到非根目录下；
- 把 2 级目录连同 1 个孙子拖到 2 级位置；
- 把根目录的"工作"目录拖到孙级。
六、收获
写完目录树这块代码，我对"树形数据"的认知刷新了：
- 数据库选模型这步必须想清楚——一旦动手就很难翻盘；
- 冗余字段是把双刃剑——给你性能也给你坑，每个写入入口都得同步它；
- 环检测和深度校验不是可选项，是用户作死操作时数据库的最后一道防线；
- 递归 CTE 不止用在删除——只要是"找子孙"这种问题，它都是最优解。
下一篇我会讲NoteUpdateDTO.tagIds这个字段的三态设计——一个看似平凡的字段，背后是 PUT 接口语义、覆盖式更新、防御式校验三层考虑