Files
Endoleap/docs/06-development.md

4.3 KiB
Raw Permalink Blame History

6. 用模型指导开发与排查

上一章 · 目录

练习:为 counter 增加“加一”按钮

先在纸上设计,再动源码。目标不是把按钮画出来,而是让它遵守事务、历史、同步和目标生命周期规则。

  1. 模型:counter 的 count 是 JSON data,Registry 校验它的合法范围。consumer.mjs 已有完整自定义组件示例,可以先理解其定义。
  2. 行为:按钮在最新状态下读取有效 target 和 count,通过受支持的命令提交 element.data。默认用户编辑进入历史与同步流程,不另写一套 fetch 保存。
  3. 显示:在 renderer 目录中登记与组件 ID、版本和结构匹配的 React renderer;由应用宿主组合模型定义与 renderer 定义。
  4. 生命周期:点击时重新确认目标,避免使用删除前捕获的 incarnation;组件卸载只清自己的事件和视图租约。
  5. 验证:检查加一后文档值、undo/redo、非法数据拒绝及旧 target 拒绝;如果改动触及协议,再验证请求与回执。不要只测试按钮文字变了。

这里不提供一段未经项目接线验证的“可直接运行插件”。练习的产物是一份变更设计和检查方案。扩展入口可从 CanvasRuntimeHost 的 extensions 与 createReactRenderers 跟踪。

同一症状,从哪层排查

症状 第一处证据 接下来问什么
一直正在打开 GraphPage 的 error、入口结果 引用、身份、新旧分流还是模型加载失败?
点击后无变化 命令 Result 被 policy、能力、schema 还是旧 target 拒绝?
文档正确但显示错误 scene projection 与 renderer 输入 会话、坐标、缓存失效还是渲染映射错误?
页面已改但刷新丢失 本地持久化结果、恢复记录 修改是否真正可靠落盘,作用域是否正确?
操作迟迟未同步 ledger、scheduler 门禁 依赖、身份、加载、持久屏障还是不确定请求阻塞?
撤销失败 History 与冲突结果 当前字段是否已变化,目标代次是否仍有效?
上传完成但节点不对 resource 记录与文档引用 上传事实、附件采用和节点编辑是否分别协调?

先确认事实在哪层首次偏离,再修对应边界。比如命令已明确 rejected,就先解释拒绝码;此时刷新 renderer 通常不能解决问题。

如何选择测试

core 测试关注规则和原子性;runtime 测试关注操作、存储与恢复;service 测试关注协议;bindings 测试关注投影、订阅与命中;浏览器与页面集成测试才覆盖真实适配器、焦点和事件。

同一条测试通过有明确边界:内存 storage 不能证明 IndexedDB 崩溃安全;模拟 transport 不能证明线上 Foundry 正确;源码加载通过也不能证明编译包 exports、Worker URL 正确。

执行前检查 package.json 和对应脚本。build:headless 会生成产物;test:headless:package 包含构建打包;页面、proxy、浏览器集成也需检查是否隐式编译或启动服务。需要构建的步骤使用用户确认的远程 runner。本教程编写只做文档和引用检查,没有重跑这些产品测试。

完成整套教程的检查

尝试不用看答案,讲解这段场景:用户打开项目,改标题,开始拖动;服务器返回上次编辑的 ACK;用户取消拖动,然后刷新。

合格的解释至少包含:

  • 入口解析真实身份并选择新旧模型;WorkspaceRuntime 取得或复用 engine。
  • 标题命令在候选根上验证,文档、历史和待同步事实一起发布。
  • 拖动是会话预览,取消不会回退已提交标题,也不会抹掉服务器 ACK。
  • 界面从文档、会话与 renderer 派生显示,不单独拥有业务真相。
  • 发送前有可靠保存要求;ACK 需要与后续本地状态协调。
  • 刷新解释本地恢复材料,不盲目覆盖为服务端最新模型;未解决请求沿原身份接续。

能讲清这段过程,就已具备定位大部分编辑链路问题的基础。接下来按实际开发目标深入资源、导入或渐进加载,而无需先通读整个仓库。