目录前言一、问题现象二、排查过程第一步看请求第二步查数据库第三步翻代码三、核心知识两个版本号的区别四、为什么会触发五、怎么修修复 1回滚后把 canvas_version 传给子组件修复 2手动保存和自动保存串行化修复 3后端 409 返回当前版本号六、总结前言最近在开发一个在线画布编辑器支持快照回滚功能。测试时发现一个诡异的 bug回滚到旧版本后再点击保存必现 409 版本冲突。查了半天才发现是两个长得像但含义不同的版本号被混用了。记录一下这个坑希望能帮到有类似场景的同学。一、问题现象正常编辑、保存都没问题。但执行以下操作后必崩画布当前版本 8进入快照历史回滚到版本 4点击保存按钮有时自动保存也会触发再点保存报错{ code: 409, msg: 版本冲突画布已被其他端更新请刷新后再操作, data: null }到这一步用户就很懵我就一个人在用哪来的其他端二、排查过程第一步看请求打开 DevTools 抓包发现保存时发的请求长这样POST /api/v1/studio/canvases/xxx/operations { items: [ { operation_type: update_node, version: 15 } ] }version: 15哪来的 15第二步查数据库回滚前drama_canvas.version 8drama_canvas_snapshot最新version 14回滚到快照 v4 后drama_canvas.version→ 9乐观锁自增了drama_canvas_snapshot新增一条 v15 的快照真相大白前端把快照版本 15 当成画布版本提交了但后端期望的是 915 ≠ 9 → 409。第三步翻代码回滚成功后后端返回{ snapshot_version: 15, // 新创建的快照编号 canvas_version: 9 // 更新后的画布乐观锁版本 }前端做了什么// 只拿了 snapshot_version 去拉快照详情 const detail await getStudioCanvasSnapshotDetailApi( canvasId, result.snapshot_version, // 15 ); // 导入了快照内容但没有把 canvas_version 传下去 (canvasRef.value as any)?.importCanvasSnapshot?.(detail);画布子组件内部保存时用的是本地缓存的一个版本号但这个值在回滚后没有被更新导致提交了错误的值。三、核心知识两个版本号的区别很多人在这个场景会踩坑因为系统里有两个叫 version 的字段但职责完全不同Canvas.versionSnapshot.version是什么画布的乐观锁版本号快照的序号什么时候变每次更新画布内容时自增每创建一个快照时自增谁在用写操作记录、更新画布内容时校验快照历史列表、回滚时定位类比Git 仓库的 HEAD commit某条记录在日志里的行号回滚后1因为内容被替换1因为创建了新的快照记录两者各自独立没有数学关系。Canvas.version 9 时Snapshot.version 可能是 15也可能还是 3——取决于这个画布一共创建过多少次快照。四、为什么会触发画了一个简化的流程图回滚前 Canvas.version 8 MAX(snapshot.version) 14 用户点击回滚到 v4 ↓ 后端 INSERT drama_canvas_snapshot (version15, contentv4.content) UPDATE drama_canvas SET contentv4.content, version9 返回 { canvas_version: 9, snapshot_version: 15 } ↓ 前端BUG 在这 收到了 canvas_version9但没有传给画布子组件 画布子组件本地缓存还是旧值或被误写为 15 ↓ 用户点击保存 前端发请求 version15 后端当前 Canvas.version9 15 ≠ 9 → 409 冲突所以后端返回 409 是正确行为它在保护数据一致性。问题出在前端版本同步的流程上。五、怎么修修复 1回滚后把 canvas_version 传给子组件回滚成功回调里加一行// 把回滚返回的 canvas_version 同步给画布子组件 (canvasRef.value as any)?.setBackendCanvasVersion?.(result.canvas_version); (canvasRef.value as any)?.importCanvasSnapshot?.(detail);子组件新增方法function setBackendCanvasVersion(version: number) { if (version 0) { backendCanvasVersion.value version; } }修复 2手动保存和自动保存串行化之前手动保存可能和自动保存并发两个请求拿到同一个 version一个成功后另一个必 409。现在都走同一个队列async function persistCanvasSnapshot(reason?: string) { await enqueuePersistTask(async () { await persistCanvasOperationRecord(); await saveStudioCanvasSnapshotApi(canvasId, { reason }); }); }修复 3后端 409 返回当前版本号即使前端没跟上后端也帮它一把# 冲突时在 data 里返回当前 Canvas.version raise errors.ConflictError( msg版本冲突画布已被其他端更新请刷新后再操作, data{current_version: current_canvas_version}, )前端收到 409 后自动用这个值更新缓存并重试用户无感知。六、总结问题原因解法回滚后保存 409快照版本号污染了画布乐观锁版本号回滚成功后显式同步canvas_version自动保存 手动保存冲突并发两个请求用同一个 version同队列串行化409 后用户不知道怎么办错误响应 data 为空后端返回current_version前端自动重试三条经验同名不代表同义——系统里有多个version字段时一定要搞清楚每个的含义和生命周期。回滚不是只读操作——它会同时推进快照序号和画布乐观锁前端需要把两个返回值都消费掉。冲突响应要有恢复路径——返回 409 的时候告诉客户端你应该用什么 version 重试而不是只返回一个错误信息。本文基于真实项目 的排查记录整理涉及后端 FastAPI SQLAlchemy 乐观锁、前端 Vue 3 TypeScript 画布编辑器。
踩坑记录：画布回滚后一直提示“版本冲突，请刷新后再操作“，排查了半天才发现是版本号搞混了
目录前言一、问题现象二、排查过程第一步看请求第二步查数据库第三步翻代码三、核心知识两个版本号的区别四、为什么会触发五、怎么修修复 1回滚后把 canvas_version 传给子组件修复 2手动保存和自动保存串行化修复 3后端 409 返回当前版本号六、总结前言最近在开发一个在线画布编辑器支持快照回滚功能。测试时发现一个诡异的 bug回滚到旧版本后再点击保存必现 409 版本冲突。查了半天才发现是两个长得像但含义不同的版本号被混用了。记录一下这个坑希望能帮到有类似场景的同学。一、问题现象正常编辑、保存都没问题。但执行以下操作后必崩画布当前版本 8进入快照历史回滚到版本 4点击保存按钮有时自动保存也会触发再点保存报错{ code: 409, msg: 版本冲突画布已被其他端更新请刷新后再操作, data: null }到这一步用户就很懵我就一个人在用哪来的其他端二、排查过程第一步看请求打开 DevTools 抓包发现保存时发的请求长这样POST /api/v1/studio/canvases/xxx/operations { items: [ { operation_type: update_node, version: 15 } ] }version: 15哪来的 15第二步查数据库回滚前drama_canvas.version 8drama_canvas_snapshot最新version 14回滚到快照 v4 后drama_canvas.version→ 9乐观锁自增了drama_canvas_snapshot新增一条 v15 的快照真相大白前端把快照版本 15 当成画布版本提交了但后端期望的是 915 ≠ 9 → 409。第三步翻代码回滚成功后后端返回{ snapshot_version: 15, // 新创建的快照编号 canvas_version: 9 // 更新后的画布乐观锁版本 }前端做了什么// 只拿了 snapshot_version 去拉快照详情 const detail await getStudioCanvasSnapshotDetailApi( canvasId, result.snapshot_version, // 15 ); // 导入了快照内容但没有把 canvas_version 传下去 (canvasRef.value as any)?.importCanvasSnapshot?.(detail);画布子组件内部保存时用的是本地缓存的一个版本号但这个值在回滚后没有被更新导致提交了错误的值。三、核心知识两个版本号的区别很多人在这个场景会踩坑因为系统里有两个叫 version 的字段但职责完全不同Canvas.versionSnapshot.version是什么画布的乐观锁版本号快照的序号什么时候变每次更新画布内容时自增每创建一个快照时自增谁在用写操作记录、更新画布内容时校验快照历史列表、回滚时定位类比Git 仓库的 HEAD commit某条记录在日志里的行号回滚后1因为内容被替换1因为创建了新的快照记录两者各自独立没有数学关系。Canvas.version 9 时Snapshot.version 可能是 15也可能还是 3——取决于这个画布一共创建过多少次快照。四、为什么会触发画了一个简化的流程图回滚前 Canvas.version 8 MAX(snapshot.version) 14 用户点击回滚到 v4 ↓ 后端 INSERT drama_canvas_snapshot (version15, contentv4.content) UPDATE drama_canvas SET contentv4.content, version9 返回 { canvas_version: 9, snapshot_version: 15 } ↓ 前端BUG 在这 收到了 canvas_version9但没有传给画布子组件 画布子组件本地缓存还是旧值或被误写为 15 ↓ 用户点击保存 前端发请求 version15 后端当前 Canvas.version9 15 ≠ 9 → 409 冲突所以后端返回 409 是正确行为它在保护数据一致性。问题出在前端版本同步的流程上。五、怎么修修复 1回滚后把 canvas_version 传给子组件回滚成功回调里加一行// 把回滚返回的 canvas_version 同步给画布子组件 (canvasRef.value as any)?.setBackendCanvasVersion?.(result.canvas_version); (canvasRef.value as any)?.importCanvasSnapshot?.(detail);子组件新增方法function setBackendCanvasVersion(version: number) { if (version 0) { backendCanvasVersion.value version; } }修复 2手动保存和自动保存串行化之前手动保存可能和自动保存并发两个请求拿到同一个 version一个成功后另一个必 409。现在都走同一个队列async function persistCanvasSnapshot(reason?: string) { await enqueuePersistTask(async () { await persistCanvasOperationRecord(); await saveStudioCanvasSnapshotApi(canvasId, { reason }); }); }修复 3后端 409 返回当前版本号即使前端没跟上后端也帮它一把# 冲突时在 data 里返回当前 Canvas.version raise errors.ConflictError( msg版本冲突画布已被其他端更新请刷新后再操作, data{current_version: current_canvas_version}, )前端收到 409 后自动用这个值更新缓存并重试用户无感知。六、总结问题原因解法回滚后保存 409快照版本号污染了画布乐观锁版本号回滚成功后显式同步canvas_version自动保存 手动保存冲突并发两个请求用同一个 version同队列串行化409 后用户不知道怎么办错误响应 data 为空后端返回current_version前端自动重试三条经验同名不代表同义——系统里有多个version字段时一定要搞清楚每个的含义和生命周期。回滚不是只读操作——它会同时推进快照序号和画布乐观锁前端需要把两个返回值都消费掉。冲突响应要有恢复路径——返回 409 的时候告诉客户端你应该用什么 version 重试而不是只返回一个错误信息。本文基于真实项目 的排查记录整理涉及后端 FastAPI SQLAlchemy 乐观锁、前端 Vue 3 TypeScript 画布编辑器。
