Documentation
¶
Overview ¶
Package fsm 提供泛型有限状态机原语:声明式定义"状态 + 事件 → 目标状态"的 合法转移表,运行时 Fire(event) 只允许沿合法转移推进,非法转移报错而非静默改状态。
解决的问题:对局(等待→进行→结算)、房间生命周期、订单、匹配状态,业务里常 用裸 if/switch 手写状态流转,容易出现非法跳转(如已结算又被改回进行中)且难审计。 本包把合法转移集中声明,把"能不能转"交给状态机校验,并在转移前后挂钩子。
泛型 S(状态)、E(事件)须为 comparable(用作 map 键),通常是自定义的 整型或字符串枚举。钩子执行顺序:OnLeave(from) → OnTransition(from,to,event) → 状态切换 → OnEnter(to)。任一钩子返回 error 则中止转移,状态不变。
并发安全:Fire 全程持锁,钩子在锁内执行(须轻量、不可回调 Fire 以免死锁)。 零值不可用,用 New / NewBuilder 构造。
Index ¶
- type Builder
- func (b *Builder[S, E]) Allow(from S, event E, to S) *Builder[S, E]
- func (b *Builder[S, E]) Build() *FSM[S, E]
- func (b *Builder[S, E]) OnEnter(fn func(to S, event E) error) *Builder[S, E]
- func (b *Builder[S, E]) OnLeave(fn func(from S, event E) error) *Builder[S, E]
- func (b *Builder[S, E]) OnTransition(fn func(from, to S, event E) error) *Builder[S, E]
- type Callbacks
- type ErrInvalidTransition
- type FSM
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder[S, E comparable] struct { // contains filtered or unexported fields }
Builder 以链式 API 声明转移表与钩子,避免手写 transition 复合键。
func NewBuilder ¶
func NewBuilder[S, E comparable](initial S) *Builder[S, E]
NewBuilder 创建以 initial 为初始状态的 Builder。
func (*Builder[S, E]) OnTransition ¶
OnTransition 设置转移钩子(状态切换前)。
type Callbacks ¶
type Callbacks[S, E comparable] struct { // OnLeave 离开 from 状态前调用。 OnLeave func(from S, event E) error // OnTransition 状态即将从 from 切到 to 时调用(状态尚未变更)。 OnTransition func(from, to S, event E) error // OnEnter 进入 to 状态后调用(状态已变更)。此钩子返回的 error 只上报,不回滚。 OnEnter func(to S, event E) error }
Callbacks 转移生命周期钩子。任一返回 error 会中止转移,状态保持不变。
type ErrInvalidTransition ¶
type ErrInvalidTransition[S, E comparable] struct { From S Event E }
ErrInvalidTransition 当前状态下该事件无合法转移。
有意做成携带 From/Event 字段的错误类型(而非 errors.New 的哨兵值): 非法转移时调用方常需知道"从哪个状态、什么事件"被拒,用 errors.As 取出字段即可。 若只需判定"是否非法转移",errors.As(err, &ErrInvalidTransition[S,E]{}) 亦可。
func (ErrInvalidTransition[S, E]) Error ¶
func (e ErrInvalidTransition[S, E]) Error() string
type FSM ¶
type FSM[S, E comparable] struct { // contains filtered or unexported fields }
FSM 泛型有限状态机。零值不可用,用 New / NewBuilder 构造。并发安全。
func (*FSM[S, E]) AvailableEvents ¶
func (f *FSM[S, E]) AvailableEvents() []E
AvailableEvents 返回当前状态下所有可触发的事件(顺序不保证)。
Source Files