使用 javascript-state-machine 的 visualize 插件:将状态机配置渲染为 GraphViz 有向图
使用 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。上面这扇门的最终渲染效果如下:
理解输出结构: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):
- 图头固定为
digraph "name" {,name默认是fsm; - 若有方向则输出
rankdir=LR;或rankdir=TB;; - 每个状态输出一行
"state";; - 每条迁移输出一行
"from" -> "to" [ 属性... ];; - 以
}收尾,行与行之间用换行连接。
其中边的属性输出顺序有讲究: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" ];
}
渲染效果:
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 用作项目封面图):
关于工厂的更多用法(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):
顺带一提: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
这依赖 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全量场景的断言,是验证输出稳定性的最佳参照。



