2. 状态机基础模型：状态定义、事件驱动、转换表、初始状态

一个可运行的埋点状态机由四个核心要素构成：状态（State）、事件（Event）、转换表（Transition Table） 和 初始状态（Initial State）。理解这些要素的职责与协作关系，是设计稳定、可扩展的埋点上报引擎的前提。

2.1 要素定义与职责边界

在实现埋点状态机之前，必须用类型系统明确表达上述四要素。下面以 Kotlin 语言为例，展示如何用枚举和 sealed class 进行结构化定义。

// 状态枚举
enum class State {
    IDLE,           // 空闲/初始
    COLLECTING,     // 正在采集
    UPLOADING,      // 正在上报
    UPLOADED,       // 上报成功
    FAILED          // 上报失败
}

// 事件密封类
sealed class Event {
    object StartCollect : Event()   // 触发采集
    object FinishCollect : Event()  // 采集完成
    object Upload : Event()         // 开始上报
    object UploadSuccess : Event()  // 上报成功
    object UploadFail : Event()     // 上报失败
    object Retry : Event()          // 重试
}

2.2 转换表的两种建模方式

转换表定义了 当前状态 + 事件 → 下一状态 的映射。常见方案有 字典映射 和 嵌套分支 两种，各有优劣。

推荐在埋点状态机中使用 嵌套分支 方式，因为埋点状态数量通常少于 10 个，嵌套分支的编译期检查能力能有效避免遗漏转换规则。

fun nextState(current: State, event: Event): State {
    return when (current) {
        State.IDLE -> when (event) {
            Event.StartCollect -> State.COLLECTING
            else -> throw IllegalTransitionException(current, event)
        }
        State.COLLECTING -> when (event) {
            Event.FinishCollect -> State.UPLOADING
            else -> throw IllegalTransitionException(current, event)
        }
        State.UPLOADING -> when (event) {
            Event.UploadSuccess -> State.UPLOADED
            Event.UploadFail -> State.FAILED
            else -> throw IllegalTransitionException(current, event)
        }
        State.UPLOADED -> when (event) {
            else -> throw IllegalTransitionException(current, event) // 终端状态
        }
        State.FAILED -> when (event) {
            Event.Retry -> State.UPLOADING
            else -> throw IllegalTransitionException(current, event)
        }
    }
}

2.3 初始状态与启动流程

埋点状态机在应用启动或模块初始化时需立刻进入初始状态。典型代码如下：

class TrackStateMachine {
    var currentState: State = State.IDLE
        private set

    fun dispatch(event: Event): State {
        val newState = nextState(currentState, event)
        onStateChanging(currentState, event, newState)
        currentState = newState
        return newState
    }

    private fun onStateChanging(old: State, event: Event, new: State) {
        // 可在此处插入埋点打点、日志记录、回调通知等
        Log.d("StateMachine", "$old + $event -> $new")
    }
}

2.4 基础模型结构图

2.5 调试与常见错误

• 未定义转换导致的崩溃：务必在 nextState 函数的 else 分支抛出带上下文的异常，并在异常捕获处输出当前状态和事件。
• 初始状态被跳过：确保状态机实例在任何 dispatch 调用之前已将 currentState 设置为初始状态，建议在 init 块中赋值。
• 事件重复触发：埋点上报过程中可能因网络回调、定时器多次触发导致重复事件，建议在事件处理前校验当前状态是否允许该事件。
• 线程安全：移动端状态机频繁在主线程和后台线程交互，应使用 synchronized 或 Mutex 保护 currentState 的读写。