State Machine 项目技术文档

1. 安装指南

1.1 使用 RubyGems 安装

你可以通过 RubyGems 安装 state_machine 库：

gem install state_machine

1.2 在项目中引入

在你的 Ruby 项目中，可以通过以下方式引入 state_machine：

require 'state_machine'

2. 项目的使用说明

state_machine 是一个用于在 Ruby 类中创建状态机的库。它允许你为任何 Ruby 类的属性定义状态机，从而简化对象状态管理。

2.1 基本概念

• 状态 (State): 对象在某一时刻的特定状态。
• 事件 (Event): 触发状态转换的动作。
• 转换 (Transition): 从一个状态到另一个状态的转换。
• 回调 (Callback): 在状态转换前后执行的代码。

2.2 示例

以下是一个简单的示例，展示了如何在 Vehicle 类中定义状态机：

class Vehicle
  attr_accessor :seatbelt_on, :time_used, :auto_shop_busy
  
  state_machine :state, :initial => :parked do
    before_transition :parked => any - :parked, :do => :put_on_seatbelt
    
    after_transition :on => :crash, :do => :tow
    after_transition :on => :repair, :do => :fix
    after_transition any => :parked do |vehicle, transition|
      vehicle.seatbelt_on = false
    end
    
    after_failure :on => :ignite, :do => :log_start_failure
    
    around_transition do |vehicle, transition, block|
      start = Time.now
      block.call
      vehicle.time_used += Time.now - start
    end
    
    event :park do
      transition [:idling, :first_gear] => :parked
    end
    
    event :ignite do
      transition :stalled => same, :parked => :idling
    end
    
    event :idle do
      transition :first_gear => :idling
    end
    
    event :shift_up do
      transition :idling => :first_gear, :first_gear => :second_gear, :second_gear => :third_gear
    end
    
    event :shift_down do
      transition :third_gear => :second_gear, :second_gear => :first_gear
    end
    
    event :crash do
      transition all - [:parked, :stalled] => :stalled, :if => lambda {|vehicle| !vehicle.passed_inspection?}
    end
    
    event :repair do
      transition :stalled => :parked, :unless => :auto_shop_busy
      transition :stalled => same
    end
    
    state :parked do
      def speed
        0
      end
    end
    
    state :idling, :first_gear do
      def speed
        10
      end
    end
    
    state all - [:parked, :stalled, :idling] do
      def moving?
        true
      end
    end
    
    state :parked, :stalled, :idling do
      def moving?
        false
      end
    end
  end
  
  state_machine :alarm_state, :initial => :active, :namespace => 'alarm' do
    event :enable do
      transition all => :active
    end
    
    event :disable do
      transition all => :off
    end
    
    state :active, :value => 1
    state :off, :value => 0
  end
  
  def initialize
    @seatbelt_on = false
    @time_used = 0
    @auto_shop_busy = true
    super() # 必须调用，否则状态不会初始化
  end
  
  def put_on_seatbelt
    @seatbelt_on = true
  end
  
  def passed_inspection?
    false
  end
  
  def tow
    # 拖车操作
  end
  
  def fix
    # 修理车辆
  end
  
  def log_start_failure
    # 记录启动失败
  end
end

2.3 使用示例

vehicle = Vehicle.new           # => #<Vehicle:0xb7cf4eac @state="parked", @seatbelt_on=false>
vehicle.state                   # => "parked"
vehicle.state_name              # => :parked
vehicle.human_state_name        # => "parked"
vehicle.parked?                 # => true
vehicle.can_ignite?             # => true
vehicle.ignite_transition       # => #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
vehicle.state_events            # => [:ignite]
vehicle.state_transitions       # => [#<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
vehicle.speed                   # => 0
vehicle.moving?                 # => false

vehicle.ignite                  # => true
vehicle.parked?                 # => false
vehicle.idling?                 # => true
vehicle.speed                   # => 10
vehicle                         # => #<Vehicle:0xb7cf4eac @state="idling", @seatbelt_on=true>

3. 项目API使用文档

3.1 状态机定义

• state_machine(attribute, options = {}): 定义一个状态机。
  • attribute: 状态机绑定的属性。
  • options: 可选参数，如 :initial 指定初始状态。

3.2 事件定义

• event(name, &block): 定义一个事件。
  • name: 事件名称。
  • block: 事件的转换逻辑。

3.3 状态定义

• state(name, options = {}): 定义一个状态。
  • name: 状态名称。
  • options: 可选参数，如 :value 指定状态的值。

3.4 回调定义

• before_transition, after_transition, around_transition, after_failure: 定义在转换前后或失败时执行的回调。

4. 项目安装方式

4.1 通过 RubyGems 安装

gem install state_machine

4.2 在项目中引入

require 'state_machine'

通过以上步骤，你可以在你的 Ruby 项目中使用 state_machine 库来管理对象的状态。