工作流状态机模块必须采用事件驱动+显式转移表+状态接口三件套设计，否则易陷入if-else嵌套与并发丢状态；转移表用map[State]map[Event]State定义，非法转移显式返回ErrInvalidTransition，各状态用指针接收器实现State接口（Enter/Exit/HandleEvent），事件为具名struct，状态机加细粒度锁，序列化采用state字符串+currentState接口双字段同步维护。
直接说结论：工作流状态机模块不是“选个库就行”，而是要按事件驱动 + 显式转移表 + 状态接口三件套来搭，否则很快会陷入 if-else 嵌套和并发丢状态的泥潭。
用 map[State]map[Event]State 定义合法转移
别把状态流转逻辑藏在 if 或 switch 里——那是给单状态用的，工作流需要可查、可测、可审计的转移规则。
- 转移表必须是值类型映射，比如
map[State]map[Event]State，不能用字符串拼接或反射推导 - 初始化时一次性注册所有合法路径，例如：
rules[PendingState][PayEvent] = PaidState - 运行时只查表不计算，避免每次调用都遍历条件分支
- 非法转移必须显式返回
ErrInvalidTransition，不能静默忽略或 panic（后者会让调用方无法 recover）
每个状态实现 State 接口，HandleEvent 用指针接收器
状态不是标签，是行为载体。如果 HandleEvent 用值接收器，那重试计数、超时定时器、临时上下文字段全都会丢失。
- 接口至少含三个方法：
Enter()、Exit()、HandleEvent(Event) (State, error) - 所有具体状态类型（如
*PendingState）必须用指针接收器实现，确保字段修改能被后续调用感知 -
HandleEvent里只做状态内副作用（如更新重试次数），不直接改外部结构体字段；新状态由返回值决定，由状态机统一赋值 - 事件类型必须是具名 struct（如
type PayEvent struct{ UserID string }），禁止用string或int当事件 ID
状态机实例必须带锁，但锁粒度要窄
工作流常被支付回调、人工操作、超时任务同时触发，不加锁必丢状态；但锁整个结构体，会导致读 Order.UserID 这类无关字段也被阻塞。
立即学习“go语言免费学习笔记（深入）”；
- 只对状态字段和转移逻辑加锁，推荐用
sync.RWMutex，读多写少场景下提升并发吞吐 - 锁范围严格限定在
currentState和transition调用之间，不要包裹日志记录或 HTTP 请求 - 避免在
HandleEvent中执行阻塞操作（如http.Do、无超时time.Sleep），否则整个状态机 goroutine 卡死 - 若需异步动作（如发 MQ、调下游），应在
Enter()或Exit()中启动 goroutine，并确保错误可回溯
序列化与数据库存储必须和状态类型严格对齐
Go 的接口值无法直接 JSON 序列化，也不能存进 MySQL；但硬存字符串又失去类型安全——折中方案是双字段维护。
- 结构体里保留一个
state string字段用于持久化（如"pending"），同时持有一个currentState State接口值用于运行时行为 - 加载时根据
state字符串构造对应状态实例，例如：switch s.state { case "pending": s.currentState = &PendingState{...} } - 两者必须严格一致：任何写入
state字段的操作，都要同步更新currentState，反之亦然 - 单元测试里应包含“从 DB 加载 → 触发事件 → 再存回 DB”完整链路，验证字符串和接口实例始终同步
最容易被忽略的是事件 struct 的字段可空性——比如 PayEvent 里 UserID 是必需字段，但反序列化时没校验就传进 HandleEvent，后续逻辑崩了却报错在下游。这类校验必须放在事件构造或解包阶段，而不是等进状态方法才检查。
