4.1 KiB
3. 一次编辑如何成立
把“改标题”翻译成命令
假设当前节点有有效 target,支持对应编辑能力。标题从“想法”改为“行动”的核心接口形态是:
engine.editor.dispatch({
type: 'element.data',
target, // 当前元素的 { id, incarnation }
patch: { title: '行动' },
});
这只是已取得 engine 后的命令示意。真实界面还要处理焦点、编辑租约、目标是否仍有效等问题。不要绕过命令直接修改 snapshot 中的 Map 或元素对象;它们是受保护的发布结果。
从命令到候选文档
editor.ts 的 dispatch 是同步 transaction 的便捷封装。事务内部先在候选文档上规划命令,得到 changes。规划会解析目标、检查宿主 policy、组件能力和字段规则;提交前还会对候选文档做整体校验。
Registry 在这里负责解释“这个组件允许什么”。一个元素存在,不等于它支持任意命令。未来版本和未知组件可以保留原始数据,但不能借此调用未安装的行为。
Change 描述实际发生的变化,OperationIntent 描述需要同步的逻辑意图,HistoryEntry 则组织用户可撤销的工作单元。它们有关联,却不是同一个对象。
为什么两个命令可以一起成功或一起失败
例如一个 counter 节点同时移动位置并把 count 改为负数。第一条命令可以在候选文档中成立,第二条违反 schema。事务最终拒绝时,候选文档被丢弃,原文档、历史、操作记录和通知均不应留下第一条命令的结果。
完整例子在 consumer.mjs:找到标有“非法事务”的部分,再与后面的合法事务比较。合法的移动与计数更新被组织成一个历史单元。
事务回调必须同步。异步读取和资源准备先在事务外完成,再带着仍需重新验证的目标进入事务。await 期间世界可能变化,不能持有一个可在稍后继续写的事务草稿。
发布边界里还有 runtime
事务成功后进入 publish,构造历史与操作等候选状态。engine 创建 Editor 时注入 reduceRuntime,将新操作合入 ledger,并整合相关资源任务;prepareRuntime 再检查所有权、加载和资源保留等规则。
这些准备在最终 state 赋值之前完成,因此“文档已改但待同步操作没有入账”不应成为一次成功提交的状态。准备钩子不做网络 I/O;如果它们偷偷产生外部写入,丢弃候选根也无法撤销外部副作用。
订阅者随后观察已发布状态,更新页面或调度后续工作。监听器发生异常不能把已经提交的文档倒回去。
撤销为什么不是恢复整个旧快照
撤销根据历史变化与当前状态执行校验,再发布补偿意图。它必须保留期间到来的有效服务端资源确认等运行事实。如果只是把整个状态替换成编辑前的快照,这些事实会丢失。
同字段冲突时撤销可能拒绝,并保持历史栈不动。删除后撤销恢复元素会产生新的 incarnation,因此此前捕获的 target 继续失效。一次无实际变化的提交可以返回 applied,但不产生新的 operation;applied 不代表必然发生写入。
跟踪任务
先跟踪 dispatch → transaction → plan → publish,再到 engine.ts 找 createEditor 的 reduceRuntime 和 prepareRuntime。标出候选状态在哪里变成发布状态。
在 core.test.mjs 阅读标题含 rejected second command、same-field conflict、async transactions 的测试。分别写出它们保护的事实。
自检
dispatch() 返回 applied,是否意味着服务器已保存?
不是。它说明本地命令已成功处理;还需区分有无实际变化、本地可靠持久化是否完成,以及操作是否收到并协调了服务器回执。下一章看页面为什么能先响应,第 5 章再看后续可靠性。