javascript-state-machine 状态机工厂(StateMachine.factory):批量实例化与向现有对象/类注入状态机行为
javascript-state-machine 状态机工厂(StateMachine.factory):批量实例化与向现有对象/类注入状态机行为
本指南围绕 javascript-state-machine 提供的 状态机工厂(State Machine Factory) 机制展开,核心解决"如何用同一套配置批量创建相互独立的状态机实例"这一实战问题。你将掌握 StateMachine.factory() 的两种调用形态(传入配置对象 / 传入已有类)、工厂实例与单例实例在数据隔离上的关键差异,以及 StateMachine.apply() 向现有对象(如 React 组件)和现有类注入状态机行为的完整做法。
从单例构造到工厂构造:为什么要引入工厂
文档中的大多数示例只构造一个状态机实例,例如经典的"物态变化"模型:
var fsm = new StateMachine({
init: 'solid',
transitions: [
{ name: 'melt', from: 'solid', to: 'liquid' },
{ name: 'freeze', from: 'liquid', to: 'solid' },
{ name: 'vaporize', from: 'liquid', to: 'gas' },
{ name: 'condense', from: 'gas', to: 'liquid' }
]
});
这里 fsm 是一个独立对象,拥有自己的 state 属性与自动生成的转换方法。但当业务中需要多个实体各自维护独立状态(例如多个任务、多个告警对象、多个 UI 组件),逐个重复书写同一份配置显然不可取。此时应当使用 State Machine Factory:它基于同一份配置产出一个 JavaScript 构造函数(即一个"类"),再由该构造函数实例化出任意多个相互独立的状态机。
使用 StateMachine.factory 创建可复用构造函数
StateMachine.factory() 接收与 new StateMachine(options) 完全相同的配置对象,返回一个构造函数,之后用 new 即可得到状态机实例:
var Matter = StateMachine.factory({ // <-- 工厂在这里被构造
init: 'solid',
transitions: [
{ name: 'melt', from: 'solid', to: 'liquid' },
{ name: 'freeze', from: 'liquid', to: 'solid' },
{ name: 'vaporize', from: 'liquid', to: 'gas' },
{ name: 'condense', from: 'gas', to: 'liquid' }
]
});
var a = new Matter(), // <-- 实例在这里被构造
b = new Matter(),
c = new Matter();
b.melt();
c.melt();
c.vaporize();
a.state; // solid
b.state; // liquid
c.state; // gas
关键观察点:
a、b、c都从'solid'出发,但彼此状态完全独立:b只执行了melt(),停在'liquid';c又执行了vaporize(),推进到'gas';而从未调用任何转换的a仍停留在'solid'。- 工厂返回的是真正的构造函数,可用
new实例化,也可继续在原型上挂载业务方法(见下文Person示例)。
实例的独立性来自哪里
从源码实现看,factory() 的核心逻辑在 src/app.js:它先根据配置构造一个共享的 Config 对象,再通过 build(cstor.prototype, config) 把公共方法挂到原型上,最后返回构造函数 cstor:
function factory() {
var cstor, options;
if (typeof arguments[0] === 'function') {
cstor = arguments[0];
options = arguments[1] || {};
}
else {
cstor = function() { this._fsm.apply(this, arguments) };
options = arguments[0] || {};
}
var config = new Config(options, StateMachine);
build(cstor.prototype, config);
cstor.prototype._fsm.config = config; // convenience access to shared config without needing an instance
return cstor;
}
而实例的私有状态 state 则在每次 new 时由 src/jsm.js 创建独立的 JSM 对象来承载:
function JSM(context, config) {
this.context = context;
this.config = config;
this.state = config.init.from;
this.observers = [context];
}
因此可以得出准确结论:每个实例是唯一对象,各自管理自己的 state 属性;而 is、can、cannot、transitions、allStates、allTransitions 等方法通过 JavaScript 正常的原型机制被所有实例共享。这一点在 test/construction.js 中也有直接断言:t.is(fsm1.allStates, MyClass.prototype.allStates) 验证了方法共享,而 fsm1.state/fsm2.state/fsm3.state 分别等于 'A'/'B'/'C' 验证了状态隔离。
工厂实例的数据与方法:一个必须注意的共享陷阱
特别注意:关于数据和状态机工厂,需要看 Data and State Machine Factories 中的特殊处理说明。
当从工厂构造多个实例时,如果配置中 data 是一个普通对象,那么该对象会被所有实例共享——这几乎可以肯定不是你想要的。看一个反面演示:
var FSM = StateMachine.factory({
init: 'A',
transitions: [ { name: 'step', from: 'A', to: 'B' } ],
data: { color: 'red' } // <-- 危险:所有实例共享同一个 color 对象
});
要保证每个实例获得独立的数据,应把 data 写成函数(工厂方法),让它在每个实例构造时被调用一次并返回新对象;构造实例时传入的参数会原样透传给该函数:
var FSM = StateMachine.factory({
init: 'A',
transitions: [ { name: 'step', from: 'A', to: 'B' } ],
data: function(color) { // <-- 使用方法:每个实例各自调用
return {
color: color
}
},
methods: {
describe: function() {
console.log('I am ' + this.color);
}
}
});
var a = new FSM('red'),
b = new FSM('blue');
a.state; // 'A'
b.state; // 'A'
a.color; // 'red'
b.color; // 'blue'
a.describe(); // 'I am red'
b.describe(); // 'I am blue'
注意:new FSM('red') / new FSM('blue') 中的构造参数 'red'、'blue' 会直接透传给 data 函数。
这条规则的底层实现在 src/config.js:Config.configureData 会把对象形式的 data 包装成 function() { return data; }(每次返回同一引用),把函数形式的 data 原样保留;随后在 src/jsm.js 的 init 中通过 this.config.data.apply(this.context, args) 执行,并 mixin 到实例上下文上。这与 test/construction.js 中"每个实例携带独立 value 并互不影响"的用例完全对应。
methods 中的方法同样被挂到原型上共享,但方法内部的 this 始终指向调用它的那个实例,因此访问 this.state、this.color 时得到的都是该实例自己的值。
工厂与初始化:init 转换对每个实例分别触发
工厂构造的类,其 init 转换(隐式或显式)会在每个实例被 new 出来时各自触发一次。例如:
var FSM = StateMachine.factory({
init: 'A',
transitions: [
{ name: 'step', from: 'A', to: 'B' },
{ name: 'step', from: 'B', to: 'C' }
]
});
var fsm1 = new FSM(), // 'init()' transition fires from 'none' to 'A' for fsm1
fsm2 = new FSM(); // 'init()' transition fires from 'none' to 'A' for fsm2
也就是说,每个实例都会独立经历从 'none' 到初始状态的初始化流程,并触发相应的生命周期事件。更多初始化细节(显式 init 转换、隐式 init 转换)参见 Initialization Options。
向已有对象应用状态机行为:StateMachine.apply
有时你并不想创建新类,而是希望给已经存在的对象(例如一个 React 组件实例、一个普通配置对象)直接赋予状态机能力。此时使用 StateMachine.apply:
var component = { /* ... */ };
StateMachine.apply(component, {
init: 'A',
transitions: [
{ name: 'step', from: 'A', to: 'B' }
]
});
调用后,component 会获得 state 属性、step() 等转换方法以及 is/can 等内省方法,并且立即进入初始状态 'A'。
注意:不要使用会与对象已有属性冲突的状态名或转换名(例如对象上已有
state或step字段,会被状态机覆盖或引发异常)。
测试 test/basics.js 给出了完整验证:对一个 { name: 'alarm' } 对象 apply 后,原属性 name 保留,state 变为 'green',且 warn/panic/calm/clear 转换都能正确推进状态。从 src/app.js 的实现看,apply 与 factory 走的是同一套 build 流程,区别仅在于 apply 直接作用于目标对象并立即调用 instance._fsm() 完成初始化。
另外,StateMachine.apply 只接受普通对象:如果目标是函数或数组会抛出 Error('StateMachine can only be applied to objects'),这一点由 src/app.js 的 build 前置校验保证,并在 test/errors.js 中对 function、[]、42 等非法目标逐一验证。
向已有类应用工厂行为:StateMachine.factory(Class, config)
如果对象是一个类(构造函数),同样可以把状态机工厂行为注入其中,但此时你必须自己负责初始化:在类的构造函数里显式调用 this._fsm()。
function Person(name) {
this.name = name;
this._fsm(); // <-- 重要:必须手动调用以完成该实例的状态机初始化
}
Person.prototype = {
speak: function() {
console.log('my name is ' + this.name + ' and I am ' + this.state);
}
}
StateMachine.factory(Person, {
init: 'idle',
transitions: [
{ name: 'sleep', from: 'idle', to: 'sleeping' },
{ name: 'wake', from: 'sleeping', to: 'idle' }
]
});
var amy = new Person('amy'),
bob = new Person('bob');
bob.sleep();
amy.state; // 'idle'
bob.state; // 'sleeping'
amy.speak(); // 'my name is amy and I am idle'
bob.speak(); // 'my name is bob and I am sleeping'
要点拆解:
StateMachine.factory的第一种重载形态就是"传入已有构造函数 + 配置对象"(对应 src/app.js 中typeof arguments[0] === 'function'的分支)。它会把状态机方法构建到Person.prototype上,因此amy.speak()、bob.sleep()都可用。this._fsm()是关键:它创建该实例私有的JSM内核并执行init(见 src/app.js)。amy、bob各自调用,所以amy停在'idle'而bob进入'sleeping',互不干扰。- 你自定义的原型方法(
speak)与状态机方法共存于同一原型链,this.state在方法中可直接读取当前实例状态。
test/basics.js 中的 Alarm 类测试与此模式一致:a、b 两个实例分别执行 warn/panic/calm/clear 时,彼此的 state 完全隔离,验证了"同一类上多个实例状态独立"这一核心保证。
方法命名:转换名如何映射为方法名
工厂或 apply 会把每个转换自动映射为实例上的方法,映射规则在 src/util/camelize.js:按 -/_ 分割单词,首单词小写,后续单词首字母大写并拼接,例如 on-before 变为 onBefore。而 src/app.js 中通过 target[camelize(transition)] = function() { return this._fsm.fire(transition, ...) } 动态生成方法——因此转换名最好采用下划线或连字符风格(如 step-1),生成的方法名即为驼峰形式(step1);若转换名已是全小写单词,方法名保持原样。
仓库中的完整实践:matter 示例
工厂模式的完整可运行示例位于 examples/matter.js:它用 StateMachine.factory 构造 Matter 类(物态 solid/liquid/gas),并在类上挂载 visualize 方法输出可视化状态图。仓库已提供对应的状态图渲染结果 examples/matter.png,该图对应的 .dot 源文件与 SVG 版本分别是 examples/matter.dot 和 [examples/matter.svg],可作为工厂构造的状态机结构的直观参考。
小结:三种形态的选择建议
| 场景 | 推荐做法 | 初始化方式 |
|---|---|---|
| 只需一个状态机实例 | new StateMachine(options) |
构造时自动完成 |
| 用同一配置批量创建独立实例 | StateMachine.factory(options) + new |
每个实例构造时自动完成 |
| 给已有对象注入状态机能力 | StateMachine.apply(obj, options) |
调用 apply 时立即完成 |
| 给已有类注入状态机能力 | StateMachine.factory(Class, options) |
必须在类构造函数中手动调用 this._fsm() |
四个通用提醒:其一,工厂 + 对象形式 data 会导致数据被所有实例共享,务必改用 data 函数;其二,避免状态名/转换名与目标对象已有属性冲突;其三,工厂实例的状态各自独立、方法原型共享;其四,已有类的初始化必须手动调用 this._fsm(),否则实例不会进入任何状态机状态。
