javascript-state-machine 状态机工厂(StateMachine.factory):批量实例化与向现有对象/类注入状态机行为

原创2026-09-24 22:33:021,895 阅读
文章标签:开发工具

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],可作为工厂构造的状态机结构的直观参考。

Matter 状态机工厂示例状态图

小结:三种形态的选择建议

场景 推荐做法 初始化方式
只需一个状态机实例 new StateMachine(options) 构造时自动完成
用同一配置批量创建独立实例 StateMachine.factory(options) + new 每个实例构造时自动完成
给已有对象注入状态机能力 StateMachine.apply(obj, options) 调用 apply 时立即完成
给已有类注入状态机能力 StateMachine.factory(Class, options) 必须在类构造函数中手动调用 this._fsm()

四个通用提醒:其一,工厂 + 对象形式 data 会导致数据被所有实例共享,务必改用 data 函数;其二,避免状态名/转换名与目标对象已有属性冲突;其三,工厂实例的状态各自独立、方法原型共享;其四,已有类的初始化必须手动调用 this._fsm(),否则实例不会进入任何状态机状态。

登录后查看全文
javascript-state-machine