跳转到内容
pstack 中文学习站

statechart

你在看 pstack 0.15.32 时的版本,最新版在这里

这张图用读者熟悉的话,展示系统如何在不同状态间变化。脚本把读图的人称为 reader,例如 readerActions 和 reader steps。读者负责判断行为是否正确。读者可以是查看产品流程的 PM、查看协议或服务的工程师,也可以是查看设计的评审者。每个状态写读者能观察到或关心的事,例如应用中的「Paying」,或锁服务中的「Lease held, write pending」。每一步写推动系统变化的事件,例如应用中的「tap Pay」、服务中的「the request reads the count」,或锁服务中的「the lease expires」。标签里不要出现变量名和动作名。

运行 node <skill dir>/scripts/statechart.mjs --help 看命令说明和图的读法。在仓库之外的临时目录里干活。命令把生成的文件写在输入文件旁边。第一次运行会通过 mise 安装 TLC 和 Java,下载约 305 MB,需要网络。帮助中的 TLC 一节说明如何使用已有的 TLC 和 Java。

已经有 TLA+ 模型,或代码、设计已经具体到可以建模时,用 from-spec。还没有模型,而且行为负责人需要在开发或改动前先达成一致时,用 from-chart。

代码已经有 TLA+ 规格时,从这份规格的副本开始。加入标签和规则需要的变量,保留规格已有的不变量。要拿代码对照这份规格做审计,就让副本按代码的实际行为建模,把没动过的规格作为 --against 传入。用作者说能通过的那份配置检查它,并把那份配置作为 --against-config 传入,除非配置用的就是规格的文件名。一份映射同时标注两个模型,所以状态和步骤要从两个模型共有的变量生成。如果标签要读取副本独有的变量,先用 "name" in v 检查,再用其他方式标注规格中的状态。模型描述代码时,每个变量和动作都要对应到审查者能打开的代码,名字取自那段代码。每个动作在代码里是不可分割的一步。动作的每个条件,把检查它的代码的文件和行号写进这个条件的注释,例如 \* pay.ts:120。

  1. 选定图的状态。读者关心、但标签会隐藏的信息要写进标签。例如屏幕仍显示「Paying」,但第二次扣款后,标签写成「Paying, charged twice」。先从少量状态开始。只有拆分能区分两个 bug,或读者必须看到一条不会改变标签的步骤时才拆,例如请求读取计数,因为图不会画出这类步骤。
  2. 读者认可的每条规则写成一个不变量,并用读者的原话作注释。规则可以针对模型里的任何状态:屏幕显示、请求返回值、存储值,或不同部分之间的消息。模型描述代码时,规则还要指出能改变该状态的代码。模型里没有对应变量,就添加变量,不要删掉规则。规则要等系统稳定后才成立时,定义 Settled == ~ENABLED System,其中 System 是不由读者触发的动作的析取。规则只在更窄的时点成立时,例如每次请求完成后,就写出表示该时点的谓词,并让规则在谓词成立时保持成立。系统必须能够到达某个目标时,写一条断言目标永不发生的规则,并用 --expect-broken 传入。打破这条规则的路径就是通往目标的路径。图仍会把目标画成违反规则的状态,stories.md 也会把它写成 bug,因此要在交接中点出每条目标规则。其他被打破的规则都报告为 bug。永远不要为了让图通过而弱化规则。
  3. 运行 from-spec,然后填写它写出的映射文件。标签放进 state 和 step。只有需要区分读者行为与周边事件时,才按动作名把读者动作列入 readerActions。所有动作都同等重要时,留空。总览太大、难以阅读时,加入 --cover。总览只保留到每个稳定状态的最短路径,以及所有 bug 路径;命令会列出省略的内容。两个 bug 因不同原因停在同一状态时,加入 cause 并写明各自的原因。要按读者关心的事给状态着色,例如「Order shipped」,就从 group 返回该分组。图例会标出各分组;PNG 中违反规则的状态会显示为红色,而不是分组颜色。
  4. 有待议的修复时,为它建模,并把模型作为 --fixed 传入。
  5. 每张图都用 --png 渲染,并逐张查看 PNG。检查每条编号路径是否按顺序读得通。标签读起来像代码,就修好 state 或 step,再跑一遍命令。
  6. 模型描述代码时,对照真实代码重放每个 bug 的经过,写成测试或现场复现,模型里一个动作对应一步。只驱动用户、客户端或系统其他部分能到达的入口,只断言它们能观察到的内容。断言自己设下的标志、或者在源码文本里查找的测试,什么也证明不了。一次运行证明了经过的一部分、读代码证明了其余部分时,说明各自证明了哪部分。测试复制了无法导入的代码时,给出复制内容的提交和行范围,并列出复制漏掉了什么。bug 复现不了,就假定是模型错了,直到你能证明并非如此。修模型,不修规则。尚无代码的设计,以 TLC trace 为证据,并在交接中说明。
  1. 画出读者认可的图。每个独立变化的部分各占一个分区,例如设备的连接状态和设备运行的任务。每条规则加一行 %% never,写上读者的原话。会停止或重启某个部分的事件,例如「the app closes」或「the process restarts」,画成一条指向后续状态的边。运行 render CHART.mmd,生成供读者查看的 PNG。
  2. 运行 from-chart。规则被打破,说明商定的图有设计 bug。把问题交给认可这张图的人。
  3. 把真实代码的守卫和变量加进 from-chart 写出的规格,再跑一遍 from-chart。它打印的每处差异,都问读者是代码错了,还是图需要修正。

把每张图的 PNG 和 Mermaid 源码交给负责决定的人。每个 bug 写一行:违反哪条规则、按图上的编号是哪几步、是否复现、建议的修复能否修好它。被打破的 PROPERTY 没有图上路径,因此提供 stories.md 点名的 TLC 反例。用了 --against 时,还要说明规格是否已经列出它:在 stories.md 点名的配置里、在规格关于模型略去了什么的说明里,还是根本没列。模型描述代码时,命令列出的条件中没有文件和行号,就不要报告规则成立。引用的每个数字都取自 summary.json。附上 stories.md 和能重新生成一切的命令。说明模型略去了什么。