使用 javascript-state-machine 的 visualize 插件:将状态机配置渲染为 GraphViz 有向图

原创2026-09-24 23:10:061,824 阅读
文章标签:开发工具

使用 javascript-state-machine 的 visualize 插件:将状态机配置渲染为 GraphViz 有向图

状态机以状态与迁移(transition)为骨架,但仅靠代码难以直观判断迁移是否完整、是否存在死锁或环。javascript-state-machine 内置的 visualize 插件可以把状态机配置一键转换成 GraphViz 的 .dot 语言,再用 GraphViz 渲染成 PNG / SVG 等图片。本文以 docs/visualization.md 为核心,结合 可视化插件源码 与 对应测试用例,完整讲解基础转换、自定义 .dot 属性(颜色、端口、方向)、工厂(Factory)可视化,以及通配符、多来源、条件迁移等复杂配置在图上如何展开。读完本文,你将能对任意 StateMachine 实例或工厂产出可渲染的 .dot 脚本,并理解输出中每一条规则背后的实现依据。

快速上手:从状态机配置到 .dot 再到图片

visualize 是一个独立函数,与主库分开打包。按官方用法,可以从 npm 包导出的 lib/visualize 引入(本仓库中对应的构建产物是 lib/visualize.js,源码入口是 src/plugin/visualize.js):

var visualize = require('javascript-state-machine/lib/visualize');

var fsm = new StateMachine({
  init: 'open',
  transitions: [
    { name: 'close', from: 'open',   to: 'closed' },
    { name: 'open',  from: 'closed', to: 'open'   }
  ]
});

visualize(fsm)

visualize(fsm) 返回的是一个字符串——一段合法的 DOT 语言脚本(不会直接生成图片):

digraph "fsm" {
  "closed";
  "open";
  "closed" -> "open" [ label=" open " ];
  "open" -> "closed" [ label=" close " ];
}

把这段脚本交给 GraphViz(开源绘图工具)即可渲染为图片,例如命令行方式:

# 先把 visualize 的输出写入 .dot 文件,再调用 GraphViz 的 dot 布局引擎
node -e "var v=require('javascript-state-machine/lib/visualize'), fsm=require('javascript-state-machine')({init:'open',transitions:[{name:'close',from:'open',to:'closed'},{name:'open',from:'closed',to:'open'}]}); require('fs').writeFileSync('door.dot', v(fsm))"
dot -Tpng door.dot -o door.png
dot -Tsvg door.dot -o door.svg

仓库的 examples 目录正好保留着这条生产流水线的产物:每个示例都有 .js(生成 DOT 的脚本)、.dot(中间产物)、.png 与 .svg(渲染结果),例如 examples/vertical_door.js、examples/vertical_door.dot、examples/vertical_door.png。上面这扇门的最终渲染效果如下:

vertical_door.png 渲染出的门状态机有向图

理解输出结构:dotify 阶段的生成规则

visualize 的实现分两个阶段(见 src/plugin/visualize.js):

function visualize(fsm, options) {
  return dotify(dotcfg(fsm, options));
}
  • dotcfg(fsm, options):把状态机配置转换成"DOT 配置"(状态列表、迁移列表、图名、方向);
  • dotify(dotcfg):把 DOT 配置逐行拼成最终的 DOT 文本。

dotify 的拼装规则非常规整(src/plugin/visualize.js):

  1. 图头固定为 digraph "name" {,name 默认是 fsm;
  2. 若有方向则输出 rankdir=LR; 或 rankdir=TB;;
  3. 每个状态输出一行 "state";;
  4. 每条迁移输出一行 "from" -> "to" [ 属性... ];;
  5. 以 } 收尾,行与行之间用换行连接。

其中边的属性输出顺序有讲究:dotify.edge.attr 会先对属性键做 Object.keys(edge).sort() 排序,再以 key="value" 的形式用 ; 连接(src/plugin/visualize.js)。所以即使你书写 dot 属性的顺序不同,同一状态机生成的文本也是稳定可比较的——这正是测试里能做精确字符串断言的前提。

还有一个细节:迁移的"标签"默认就是迁移名,且会被 pad 函数包上空格,即 label=" close " 而不是 label="close"(src/plugin/visualize.js)。空格是为了让 GraphViz 渲染时标签与箭头留出视觉间距;如果你通过 dot 属性自定义了 label,则会覆盖这个默认值。

对于完全没有状态和迁移的空状态机,输出也依然合法:

digraph "fsm" {
}

该行为由测试 dotify empty 明确锁定(test/plugin/visualize.js)。

增强可视化:自定义图名、方向与边的 dot 属性

visualize 接受第二个可选参数 options,同时每个迁移声明可以携带一个 dot 对象,把任意 GraphViz 边属性透传给渲染:

var fsm = new StateMachine({
  init: 'closed',
  transitions: [
    { name: 'open',  from: 'closed', to: 'open',   dot: { color: 'blue', headport: 'n', tailport: 'n' } },
    { name: 'close', from: 'open',   to: 'closed', dot: { color: 'red',  headport: 's', tailport: 's' } }
  ]
});
visualize(fsm, { name: 'door', orientation: 'horizontal' });

生成结果如下——注意 name 决定了 digraph 的名字,orientation: 'horizontal' 产生了 rankdir=LR;,而每条迁移的 dot 属性被完整合并进方括号:

digraph "door" {
  rankdir=LR;
  "closed";
  "open";
  "closed" -> "open" [ color="blue" ; headport="n" ; label=" open " ; tailport="n" ];
  "open" -> "closed" [ color="red" ; headport="s" ; label=" close " ; tailport="s" ];
}

渲染效果:

horizontal_door.png 增强后的横向门状态机

options 参数一览

参数 取值 效果 实现依据
name 任意字符串 设置 digraph 的图名,默认 fsm dotcfg 读取 options.name 并写入 result.name(src/plugin/visualize.js)
orientation 'horizontal' | 'vertical' 横向输出 rankdir=LR,纵向输出 rankdir=TB;不传则不输出 rankdir dotcfg.rankdir 的映射(src/plugin/visualize.js)
init true | false 是否把初始化迁移(init transition)也画成一条边,默认不画 见下文"显示初始化迁移"小节

迁移上的 dot 属性

迁移声明里的 dot: { ... } 对象会被原样合并到生成的边属性中(src/plugin/visualize.js):

output.push(mixin({}, { from: from, to: to, label: pad(name) }, dot || {}))

mixin 的合并顺序是"默认值在前、你的 dot 在后",所以 dot 中的同名键(例如 label)可以覆盖默认标签,测试 dotcfg with custom transition .dot edge markup 对此有精确断言(test/plugin/visualize.js)。常用的 GraphViz 边属性包括:

  • color:边颜色,如 'red'、'blue';
  • headport / tailport:箭头/箭尾落在节点边框的方位(GraphViz 的罗盘点语法,取值如 n、s、e、w、ne、nw、se、sw),用于避免多边重叠、理清布线;
  • label:覆盖默认迁移名标签;
  • 其他任何 GraphViz 支持的属性(如 style、arrowhead)同样可以直接写入。

需要提醒的是:dot 属性只是被透传到 DOT 文本,端口、颜色等的实际绘制由 GraphViz 完成,visualize 只负责"如实转述"。

可视化状态机工厂(State Machine Factory)

同一个 visualize 函数也接受工厂(StateMachine.factory(...) 的返回值)作为参数。工厂是一个构造函数,而单个实例是一个对象,插件通过 dotcfg.fetch 分别取到它们的内部配置(src/plugin/visualize.js):

dotcfg.fetch = function(fsm) {
  return (typeof fsm === 'function') ? fsm.prototype._fsm.config
                                     : fsm._fsm.config
}

也就是说:传入构造函数(工厂)时读取其原型上的 _fsm.config,传入实例时读取实例上的 _fsm.config——两套配置指向同一份迁移定义,所以可视化的结果与实例化多少次无关。

官方文档中的物态示例(examples/matter.js 就是该示例的仓库实现,工厂上还挂了一个 Matter.visualize() 便捷方法):

var Matter = StateMachine.factory({
  init: 'solid',
  transitions: [
    { name: 'melt',     from: 'solid',  to: 'liquid', dot: { headport: 'nw' } },
    { name: 'freeze',   from: 'liquid', to: 'solid',  dot: { headport: 'se' } },
    { name: 'vaporize', from: 'liquid', to: 'gas',    dot: { headport: 'nw' } },
    { name: 'condense', from: 'gas',    to: 'liquid', dot: { headport: 'se' } }
  ]
});

visualize(Matter, { name: 'matter', orientation: 'horizontal' })

生成的 DOT 文本:

digraph "matter" {
  rankdir=LR;
  "solid";
  "liquid";
  "gas";
  "solid" -> "liquid" [ headport="nw" ; label=" melt " ];
  "liquid" -> "solid" [ headport="se" ; label=" freeze " ];
  "liquid" -> "gas" [ headport="nw" ; label=" vaporize " ];
  "gas" -> "liquid" [ headport="se" ; label=" condense " ];
}

渲染效果(同时被 README.md 用作项目封面图):

matter.png 物态状态机工厂渲染结果

关于工厂的更多用法(new Matter() 多实例、给既有类挂载工厂行为等)可参考 docs/state-machine-factory.md。

复杂配置:多 from、同名迁移、通配符与条件迁移

可视化面对的不只是简单的一对一迁移。visualize 在展开迁移时有一套完整的递归规则(src/plugin/visualize.js),理解它们才能读懂复杂状态机生成的图。

多来源(from 数组)与同名迁移

向导(Wizard)示例展示了 from 是数组时的展开行为,以及多个 step 同名迁移各自成边:

var Wizard = StateMachine.factory({
  init: 'A',
  transitions: [
    { name: 'step',  from: 'A',               to: 'B', dot: { headport: 'w',  tailport: 'ne' } },
    { name: 'step',  from: 'B',               to: 'C', dot: { headport: 'w',  tailport: 'e' } },
    { name: 'step',  from: 'C',               to: 'D', dot: { headport: 'w',  tailport: 'e' } },
    { name: 'reset', from: [ 'B', 'C', 'D' ], to: 'A', dot: { headport: 'se', tailport: 's' } }
  ]
});

visualize(Wizard, { orientation: 'horizontal' })

from: ['B','C','D'] 被展开成三条独立的 reset 边,同名迁移 step 则按照声明顺序各画一条:

digraph "wizard" {
  rankdir=LR;
  "A";
  "B";
  "C";
  "D";
  "A" -> "B" [ headport="w" ; label=" step " ; tailport="ne" ];
  "B" -> "C" [ headport="w" ; label=" step " ; tailport="e" ];
  "C" -> "D" [ headport="w" ; label=" step " ; tailport="e" ];
  "B" -> "A" [ headport="se" ; label=" reset " ; tailport="s" ];
  "C" -> "A" [ headport="se" ; label=" reset " ; tailport="s" ];
  "D" -> "A" [ headport="se" ; label=" reset " ; tailport="s" ];
}

渲染效果(examples/wizard.png):

wizard.png 向导状态机多来源迁移渲染

顺带一提:ATM 示例(examples/atm.dot)展示了更大规模的应用——一笔完整的 ATM 取款/存款流程包含 16 条迁移、12 个状态,visualize(ATM) 同样能直接生成完整图(见 examples/atm.js 与渲染结果 examples/atm.png)。它演示了一个重要事实:同一个状态可以出现在多条迁移的 to 中(如 continue),同名 provide 迁移也可以在不同阶段复用,visualize 全部如实画出,不会遗漏也不会去重。

通配符与缺省来源/去向

状态机语法支持用通配符 *(config.defaults.wildcard)表达"任意状态"(参见 docs/states-and-transitions.md)。dotcfg.transition 对它的处理是展开而非缩略:

  • from 是数组:递归为每个来源各生成一条边;
  • from 是 * 或缺失:遍历全部状态,为每个状态生成一条指向 to 的边;
  • to 是 * 或缺失:生成一条"从 from 回到 from"的自环边(self-loop);
  • to 是一个函数(条件迁移):直接跳过不画——因为目标状态运行时才计算得出,无法静态表达。

测试用例对上述规则有非常完整的锁定:dotcfg for fsm with wildcard/missing :from(test/plugin/visualize.js)与 dotcfg for fsm with wildcard/missing :to(test/plugin/visualize.js)分别展示了 from: '*'、缺失 from、to: '*'、缺失 to 甚至 '*' -> '*' 的展开结果;dotcfg for fsm - conditional transition is not displayed(test/plugin/visualize.js)则验证了函数型 to 不会出现在输出中。

需要特别留意通配符展开后可能出现的 "none" 状态:from 缺失时它遍历的是运行时已注册的状态列表,而 from: '*' 展开时还会包含初始化占位状态 none(config.init.from 的默认值),所以图中可能出现 "none" -> "X" 这样的边。这属于展开机制的正常表现,画图时按需甄别即可。

显示初始化迁移:options.init

默认情况下,visualize 不会把初始化迁移画成一条边,同时会把隐含的 init.from 占位状态(通常是 none)从状态列表中剔除(src/plugin/visualize.js):

dotcfg.states = function(config, options) {
  var index, states = config.states;
  if (!options.init) { // if not showing init transition, then slice out the implied init :from state
    index  = states.indexOf(config.init.from);
    states = states.slice(0, index).concat(states.slice(index+1));
  }
  return states;
}

如果你希望把"进入初始状态"这一动作也画出来,可以传入 init: true,同时初始化配置需要是"对象形态"以便携带名称与 dot 属性(初始化配置的完整说明见 docs/initialization.md):

var fsm = new StateMachine({
  init: { name: 'boot', from: 'booting', to: 'ready', dot: { color: 'red' } }
});

visualize(fsm, { init: true })

此时 dotcfg.transitions 会先输出一条 booting -> ready 的 boot 边,再输出普通迁移(src/plugin/visualize.js)。测试 dotcfg for state machine - optionally include :init transition 精确对比了 init: true 与 init: false(缺省)两种输出(test/plugin/visualize.js)。

实现细节与测试保障

为什么能拿到原始迁移声明

可视化插件读取的不是运行时映射表,而是构造时传入的原始 transitions 数组:

transitions = config.options.transitions || [], // easier to visualize using the ORIGINAL transition declarations rather than our run-time mapping

(src/plugin/visualize.js)

这依赖 Config 在构造时保留原始 options 的做法——src/config.js 的注释写明:"preserving original options can be useful (e.g visualize plugin)"。这也解释了为什么 from: ['B','C','D'] 这样的数组写法能原样保留:运行时映射早已把它打平成多条记录,只有原始声明还保持着开发者书写的结构。

两阶段设计与导出

插件把"配置 → DOT 配置"(dotcfg)与"DOT 配置 → DOT 文本"(dotify)拆成两个独立阶段并公开导出(src/plugin/visualize.js):

visualize.dotcfg = dotcfg;
visualize.dotify = dotify;

这意味着你可以在不接触状态机的前提下,直接构造一个 DOT 配置对象交给 dotify 渲染;测试文件也正是这样分别对两个阶段做单元验证的(见 test/plugin/visualize.js 中 TEST FSM => DOTCFG 与 TEST DOTCFG => DOT OUTPUT 两大区块)。

打包产物

浏览器/构建场景可以直接使用 webpack 打包出的 lib/visualize.js:它以 UMD 形式暴露 StateMachineVisualize,支持 CommonJS、AMD 与浏览器全局变量三种加载方式,逻辑与 src/plugin/visualize.js 完全一致。主库与插件的打包配置可参见 webpack.config.js。

实用建议

  • 先 DOT 后渲染:visualize 只输出文本,务必把结果写入 .dot 文件后再交给 dot 引擎(dot -Tpng / dot -Tsvg / dot -Tpdf),便于调试与版本管理;
  • 善用端口属性:状态多、迁移密的图优先为关键迁移配置 headport / tailport,能显著降低边的交叉;不同颜色标注"正向/回退"迁移可读性更好;
  • 通配符迁移会膨胀图:from: '*' 会为每个状态生成一条边,状态很多时图会非常密集,可考虑在可视化前评估是否改写成显式 from 列表;
  • 条件迁移不会出现在图中:to 为函数的迁移无法静态展开,属设计使然,画图时请自行补充说明;
  • 测试是现成的行为规范:如果你自定义了类似插件,test/plugin/visualize.js 中从空状态机到 kitchen sink 全量场景的断言,是验证输出稳定性的最佳参照。
登录后查看全文
javascript-state-machine