EmDash 内容编辑器保存冲突防护:修复发布操作覆盖他人更新版本的问题
EmDash 内容编辑器保存冲突防护:修复发布操作覆盖他人更新版本的问题
导读
在多作者协作编辑同一篇内容的场景下,"编辑者基于旧版本写作、他人已抢先保存新版本"的冲突是内容管理系统的经典难题。本文围绕 EmDash(基于 Astro 的全栈 TypeScript CMS)管理后台 @emdash-cms/admin 包的一次重要补丁(见 .changeset/publish-actions-save-conflict.md),深入讲解其如何修复"内容编辑器在显示冲突提示时,仍将作者副本保存到更新的版本上"的数据覆盖隐患,并剖析发布、定时发布、取消定时、取消发布、修改发布日期等操作在冲突期间的全新行为语义,以及 Save anyway 的取舍逻辑。读完本文,你将理解 EmDash 编辑器的乐观并发控制(optimistic concurrency)设计,掌握冲突提示的触发条件、各操作被拒或被允许的边界,以及对应的源码实现与测试验证路径。
一、问题背景:版本冲突下的"先保存再发布"竞态
EmDash 的内容模型采用基于版本令牌(revision token)的乐观并发控制:编辑器打开条目时拿到一个 _rev 版本令牌,保存时把令牌随请求一起提交;服务端发现令牌与当前存储版本不一致时,返回 409 CONFLICT,拒绝这次写入,提示"内容自上次读取后已被修改"。
在本次补丁之前,ContentEditor 存在一个危险的竞态:当编辑器的保存请求因版本冲突被拒绝、页面上已经亮起"This entry changed somewhere else"的红色提示时,发布(Publish)、定时发布(Schedule)、取消定时(Unschedule)、取消发布(Unpublish)、修改发布日期(Change publication date) 这五类操作仍然会"先保存编辑器里的副本、再执行操作本身"。也就是说,编辑器里那份基于过期版本、且未经作者明确确认的旧副本,会被悄悄写回服务端并覆盖他人已保存的新版本,随后发布还会把它变成线上内容——作者甚至可能根本不知道自己覆盖了同事的更新。
修复后的核心原则是:冲突一旦出现,任何"隐式的先保存后执行"都被禁止,只有作者显式点击 Save anyway 才允许用编辑器副本覆盖新版本。 这个原则贯穿了后续所有小节描述的改动。
二、冲突期间的操作行为矩阵:禁用、拒绝与保持等待
补丁为冲突期间的五类发布相关操作定义了清晰的行为边界,可以从源码与测试中逐条验证。
2.1 发布控件:直接禁用
冲突期间,发布相关控件一律处于禁用状态。在 ContentEditor.tsx 中,无论桌面端还是移动端、普通模式还是免打扰(distraction-free)模式,PublishActions 都传入 disabled={hasSaveConflict};设置面板里的 SettingsActionBar 同样使用 publishDisabled={hasSaveConflict}(见 ContentEditor.tsx)。
即便冲突是在发布确认对话框已经打开之后才到达的,对话框里的"Publish changes"按钮也会被禁用。测试 publish-autosave-race.test.tsx 专门验证了这一点:冲突到达后点击已打开的对话框中的发布按钮,断言没有任何 publish 请求发出,服务端条目仍保持另一位作者保存的内容。
2.2 定时发布、取消定时、取消发布:运行时拒绝并提示
这三类操作在 UI 上通过 disabled={publishingPending || hasSaveConflict} 同步禁用(见 ContentEditor.tsx),同时底层还多了一道运行时防线:即使控件已经打开、对话框已经填好,真正提交时仍会被拒绝。
所有定时/发布相关变更都会经过 runScheduleChange 这个统一入口(ContentEditor.tsx),它首先检查:
if (hasSaveConflictRef.current) {
return Promise.reject(
new Error(
t`This entry changed somewhere else. Save anyway, or reload to get the newer version.`,
),
);
}
测试 publish-autosave-race.test.tsx 验证了"冲突到达时已打开的定时对话框提交被拒绝"的场景:对话框内显示上述冲突提示文案,且没有任何 schedule 请求发出,服务端数据保持新版本。handlePublish 同样在入口处检查 hasSaveConflictRef.current(ContentEditor.tsx),构成双保险。
2.3 修改发布日期:对话框内拒绝
修改发布日期的操作单独走 handlePublishedAtChange,它复用 runScheduleChange 并传入专属的错误文案 Fix invalid fields before changing the publication date(ContentEditor.tsx)。但冲突拒绝走的是通用文案:
This entry changed somewhere else. Save anyway, or reload to get the newer version.
测试 publish-autosave-race.test.tsx 验证:冲突期间在"Change publication date"对话框里修改分钟数并点击 Save date,对话框展示冲突拒绝文案,且 没有发出任何日期更新请求,服务端仍是另一位作者的版本。
2.4 冲突到达时已在等待的保存:不再发送
发布、定时、取消定时、取消发布、改日期这些操作在执行前需要"先刷新保存编辑器当前副本",而刷新保存通过 editorSaveQueueRef 串行化排队。补丁的关键修复之一是:如果一条保存请求在排队期间冲突已经到达,那么它到达队列头部时会被放弃,而不是发送出去。
这由路由层(编辑页容器)的 serializeEditorSave 保证(router.tsx):
const result = editorSaveQueueRef.current.then(() => {
// The token the recovery fetched is only for a save the writer starts
// while the conflict shows; anything else would write over a version
// they have not seen.
if (!savesOverConflict && conflictedEntryIdRef.current === id) {
throw new Error(
t`This entry changed somewhere else. Save anyway, or reload to get the newer version.`,
);
}
return operation();
});
只有显式标记为 explicitSave(即作者主动点击 Save anyway)的保存,才允许越过冲突继续执行。测试 publish-autosave-race.test.tsx 与 editor-save-conflict.test.tsx 分别覆盖了"冲突在发布等待自动保存期间到达"与"保存因 URL 字段非法无法启动"的场景,均确认等待中的保存不会发出。
三、表单内容的保护:作者输入不被新版本替换
冲突提示出现时,表单中作者输入的内容必须原样保留,绝不能因为服务端重新拉取(refetch)了较新版本而把作者的草稿静默覆盖掉。这是本次补丁另一项关键行为。
在 ContentEditor.tsx 的条目同步副作用中,对 setFormData 的调用被三个条件门控:
if (!isPublishingRef.current && !autosaveJustCompleted && !hasSaveConflictRef.current) {
setFormData(item.data);
setSlug(item.slug || "");
...
}
一旦 hasSaveConflict 为真,来自服务端的新版本不会回填到表单,作者的输入得以保留。hasSaveConflictRef 是一个在渲染前同步更新的 ref(ContentEditor.tsx),确保"尚未重新渲染的控件"也能读到最新冲突状态,避免竞态。
3.1 自动保存同步暂停
冲突期间自动保存也被按下了暂停键。自动保存 effect 中显式检查冲突:
// Autosaving through a conflict would put the writer's copy over the other
// version without them ever choosing to.
if (hasSaveConflict) {
return;
}
见 ContentEditor.tsx。自动保存的防抖间隔为 AUTOSAVE_DELAY = 2000 毫秒(ContentEditor.tsx),冲突出现后这一机制整体让路,等待作者做出明确决定。测试 editor-save-conflict.test.tsx 验证:冲突后继续编辑并推进时间 10 秒,只发出了一次 PUT(即触发冲突的那次),后续自动保存全部被抑制。
四、有意的例外:作者与 SEO 字段仍可写入
补丁并非一刀切地冻结整个表单。更改作者(Author)或 SEO 字段仍然会写入,并且仍然会替换它发送到新版本上的内容——但有两个重要限制:
- 不再清除冲突提示:只有来源为
editor的保存才能解除冲突状态。在 router.tsx 的保存成功回调中:
// Only a save the writer started resolves the conflict. An author or SEO
// write carries the recovered token too, and clearing the notice for one
// would hand the editor's stale copy a token the server accepts.
if (variables.source === "editor") {
setConflictedEntryId((current) => (current === variables.targetId ? "" : current));
}
这意味着作者/SEO 的写入即使成功,也不会让页面"假装冲突已经解决"——因为这类写入携带的是恢复流程取回的令牌,一旦清除提示,后续编辑器的保存就会带着这个令牌覆盖作者尚未看过的新版本。
- 表单内容继续保留:由于冲突未解除,作者在表单里输入的内容不会被 refetch 的新版本替换。
测试 publish-autosave-race.test.tsx 专门验证了这一行为:冲突期间切换作者、继续编辑标题,Save anyway 按钮始终可见,标题输入框始终保持"Writer copy",而服务端数据仍是"Other writer"——即编辑器副本没有被隐式写回。
五、Save anyway:作者显式选择的唯一覆盖通道
冲突提示 Banner(ContentEditor.tsx)是整条交互链的核心出口:
{hasSaveConflict && (
<Banner
variant="error"
role="alert"
title={t`This entry changed somewhere else after you opened it.`}
description={t`What you typed is still here. Saving replaces the newer version.`}
action={
<Button size="sm" variant="secondary" type="button" onClick={submitSave}>
{t`Save anyway`}
</Button>
}
/>
)}
文案清楚交代了两件事:你的输入还在;点击保存会替换新版本。点击 Save anyway 后,submitSave 走正常的保存路径(onSave(createSavePayload())),但此时路由层的 serializeEditorSave 以 explicitSave=true 放行,保存携带恢复流程取回的最新 _rev 令牌,服务端接受这次写入。测试 editor-save-conflict.test.tsx 验证了最终 PUT 请求体包含 data: { title: "Writer copy" } 与 _rev: "rev-moved"(冲突后的新令牌)。
5.1 冲突状态如何建立与解除
在 router.tsx 的 recoverFromSaveConflict 中,收到 409 CONFLICT 后:
- 先把条目标记为冲突(
setConflictedEntryId(entryId)); - 然后重新拉取服务端最新版本(仅为取回新令牌,不会回填表单);
- 如果这一步失败(连新版本都读不到),则撤销冲突标记并返回失败——因为丢弃被拒的令牌会让下一次保存变成"盲写",而向用户承诺"可以覆盖"却又无法兑现,只会制造新的覆盖风险。
冲突的解除只发生在两类成功场景:编辑器显式保存成功(source === "editor",见 router.tsx),或作者主动"Discard changes"放弃草稿(测试 editor-save-conflict.test.tsx 验证丢弃后提示消失)。错误识别由 isSaveConflict 完成:error instanceof ApiResponseError && error.code === "CONFLICT"(router.tsx)。
六、配套测试:冲突与发布竞态的完整覆盖
本次修复在 packages/admin/tests/ 下新增并强化了两组测试,可作为理解行为契约的"活文档":
-
editor-save-conflict.test.tsx:模拟一个"首次 PUT 返回 409、后续接受保存"的 mock 服务端,覆盖冲突后自动保存停止、
Save anyway携带新令牌保存、无法读取新版本时报错(提示消失而非提供虚假的覆盖承诺)、URL 非法时保存被拦截且提示保留、丢弃草稿后提示关闭等场景。 -
publish-autosave-race.test.tsx:使用可手动 resolve 的延迟响应(
deferredResponse)精确编排请求时序,覆盖发布前刷新保存与在途自动保存的排队顺序、发布/定时/取消定时/改日期前的副本刷新、刷新失败(网络错误、500、409)时后续操作一律不执行、重复点击发布按钮的合并(coalescing)、冲突期间发布/取消发布控件禁用、冲突期间打开的对话框提交被拒、作者变更不清除冲突、Save anyway后发布恢复可用等完整矩阵。
两处测试共享同一套 mock 服务端模式:以 _rev 令牌校验模拟真实 handler,令牌不匹配返回 409,从而在单元层面真实还原了服务端的乐观并发语义。
七、小结
EmDash 通过本次补丁,把"保存冲突"从"数据可能被隐式覆盖的隐患"升级为"受控的、需要作者显式决策的交互状态":
- 冲突期间,发布、定时、取消定时、取消发布、改发布日期五类操作要么禁用、要么在运行时被拒绝,任何隐式的先保存后执行都不再发生;
- 等待中的保存请求在队列头部被拦截,冲突到达后不再发出;
- 作者输入保留在表单中,自动保存暂停,新版本不会被静默回填;
- 作者/SEO 字段写入作为有意的例外仍被允许,但不会解除冲突,防止后续保存滥用恢复令牌;
Save anyway成为唯一、且必须由作者显式触发的覆盖通道,携带恢复后的最新令牌完成写入。
这套机制的价值在于:把"覆盖他人更新"这个高风险操作的裁决权从隐式流程交还给显式的人为决策,同时用 editor 来源标记与队列拦截从机制上杜绝了绕过。对构建多作者内容协作系统的开发者而言,ContentEditor.tsx 中的冲突门控模式(渲染前同步的 ref + 队列串行化 + 来源标记)与 router.tsx 中的冲突恢复流程,是值得直接借鉴的实现范本。