业务状态机设计实战：从if/else到可控状态流转

在业务系统中把一个对象从一种状态迁移到另一种状态几乎贯穿所有核心模块。以标题中的剧情为例残虹先被捕然后进入收容中心最终在监狱服刑而珀塞特经过审批获得戴罪立功机会完成考核后可以回到学校重新生活。这段剧情如果做成代码就是典型的业务状态流转。状态一旦多起来靠if/else判断状态、执行动作代码会变得难以维护状态重复更新、非法流转、缺少审计、并发覆盖等问题也会随之出现。这篇文章会从一个虚构的状态流转案例出发先梳理业务状态机模型再手写一个轻量级状态机核心然后把“被捕、收容、服刑、戴罪立功、返校”的完整流程接入代码。文章会覆盖状态机设计、守卫条件、业务动作、审计日志、单元测试、并发与幂等问题。适合后端开发、中间件开发以及刚接触状态机设计但想在项目里落地的读者。以下案例中的人名和事件只用于讲解状态机设计不映射任何现实司法流程。1. 先把业务状态梳理清楚状态、事件、转换表1.1 不要继续用 if/else 管理状态很多业务模块早期会写成这样if (FREE.equals(status)) { if (CAPTURE.equals(action)) { status ARRESTED; // 执行抓捕归档 } } else if (ARRESTED.equals(status)) { if (DETAIN.equals(action)) { status DETAINED; // 执行收容 } }这种写法在状态只有两三个的时候没有任何问题。状态一旦增加到六个、事件增加到五个分支数量会快速增长代码会同时混入状态判断、业务动作和异常处理。新加一个状态时可能需要改动多处if/else而且很难回答两个关键问题当前状态下哪些事件是合法的从状态 A 到状态 B需要满足什么条件执行哪些动作状态机就是用来集中管理这些规则的。它把“当前状态、触发事件、目标状态、守卫条件、业务动作”组织成一张可配置的转换表让状态流转变成可控、可测试、可审计的过程。1.2 状态机核心概念状态、事件、转换、守卫、动作状态机的五个核心要素可以用一张表直接说清楚。概念含义在本案例中的作用状态对象当前所处阶段在逃、被捕、收容、服刑、戴罪立功、返校事件外部触发的动作抓捕、收容、判刑、戴罪立功审批、考核通过转换从一个状态到另一个状态被捕后经过收容进入服刑守卫转换是否允许执行的条件只有通过审批才能戴罪立功动作状态转换成功后执行的副作用写审计日志、发通知、生成业务单据在代码中状态和事件最好都使用枚举定义避免到处写魔法字符串。转换表是状态机的核心数据守卫负责校验业务条件动作负责执行业务副作用。1.3 先画一张状态转换表再写代码在动手写状态机之前建议先在纸上把状态转换表列出来。本文案例可以整理成以下规则当前状态触发事件目标状态守卫条件动作在逃抓捕被捕抓捕原因不能为空完成抓捕归档被捕收容收容无生成收容编号收容判刑服刑必须有法院文书生成服刑记录收容戴罪立功审批戴罪立功必须通过立功审批生成戴罪立功记录戴罪立功考核通过返校考核结果必须为通过生成返校通知这张表有两个要点。第一同一个当前状态下不同事件可以走向不同目标状态。收容状态既能通过“判刑”走向服刑也能通过“戴罪立功审批”走向戴罪立功。这说明状态机不是一条直线而是一张有分支的图。第二守卫条件决定事件是否合法。没有法院文书就不能判刑没有通过审批就不能戴罪立功。如果业务规则发生变化只需要调整转换表里的守卫条件不需要改动调用方代码。2. 自己实现一个轻量状态机核心2.1 为什么先自己实现而不是直接引入框架市面上有 Spring StateMachine、Flowable、Activiti 等成熟框架。对于学习状态机原理自己实现一个最小核心更合适因为代码足够短并能清楚展示每次状态转换发生了什么。这里实现一个与业务无关的泛型状态机类。它支持任意状态枚举、任意事件枚举、任意业务上下文对象核心能力只有三个注册转换规则根据当前状态和事件找到对应转换执行守卫校验和业务动作后返回目标状态。2.2 定义状态机和上下文模型先定义状态机和上下文类型。import java.util.HashMap; import java.util.Map; public class StateMachineS, E, C { public interface GuardS, E, C { boolean test(StateContextS, E, C context); } public interface ActionS, E, C { void execute(StateContextS, E, C context); } public static class StateContextS, E, C { private final S source; private final E event; private final C payload; public StateContext(S source, E event, C payload) { this.source source; this.event event; this.payload payload; } public S getSource() { return source; } public E getEvent() { return event; } public C getPayload() { return payload; } } public static class TransitionS, E, C { private final S source; private final E event; private final S target; private final GuardS, E, C guard; private final ActionS, E, C action; public Transition(S source, E event, S target, GuardS, E, C guard, ActionS, E, C action) { this.source source; this.event event; this.target target; this.guard guard; this.action action; } public S getSource() { return source; } public E getEvent() { return event; } public S getTarget() { return target; } public GuardS, E, C getGuard() { return guard; } public ActionS, E, C getAction() { return action; } } private final MapS, MapE, TransitionS, E, C transitions new HashMap(); public void addTransition( S source, E event, S target, GuardS, E, C guard, ActionS, E, C action) { transitions.computeIfAbsent(source, k - new HashMap()) .put(event, new Transition(source, event, target, guard, action)); } public S fire(S current, E event, C payload) { MapE, TransitionS, E, C eventMap transitions.get(current); if (eventMap null) { throw new IllegalStateException(当前状态 current 没有配置任何流转); } TransitionS, E, C transition eventMap.get(event); if (transition null) { throw new IllegalStateException(状态 current 不允许事件 event); } StateContextS, E, C context new StateContext(current, event, payload); GuardS, E, C guard transition.getGuard(); if (guard ! null !guard.test(context)) { throw new IllegalStateException(事件 event 未通过守卫条件); } ActionS, E, C action transition.getAction(); if (action ! null) { action.execute(context); } return transition.getTarget(); } }这个状态机的核心逻辑只有fire方法。它先根据当前状态找到事件映射表再根据事件找到转换规则然后执行守卫和动作最后返回目标状态。整个过程非常直观。2.3 给状态机加上重复转换检查上面的最小实现已经可以工作但有一个容易出问题的地方同一个状态和事件只能配置一条转换规则。如果配置了两条后面的会覆盖前面的排查时会非常困难。可以在addTransition里增加冲突检查public void addTransition( S source, E event, S target, GuardS, E, C guard, ActionS, E, C action) { MapE, TransitionS, E, C eventMap transitions.computeIfAbsent(source, k - new HashMap()); if (eventMap.containsKey(event)) { throw new IllegalArgumentException( 状态 source 的事件 event 已存在转换配置); } eventMap.put(event, new Transition(source, event, target, guard, action)); }这样在启动阶段就能发现重复配置而不是运行到某个分支时才暴露出问题。这种“尽早失败”的策略在生产环境里非常重要。3. 把案例接入状态机从残虹到珀塞特3.1 定义业务状态和事件枚举现在把案例翻译成枚举。public enum PersonState { FREE, // 在逃或正常 ARRESTED, // 被捕 DETAINED, // 收容 IMPRISONED, // 服刑蹲牢 PROBATION, // 戴罪立功 SCHOOL // 返校生活 }public enum PersonEvent { CAPTURE, // 抓捕 DETAIN, // 收容 SENTENCE, // 判刑入监 REDEEM, // 戴罪立功审批 GRADUATE // 考核通过返校 }业务上下文除了保存人员 ID 和操作人还需要保存守卫条件要用的字段。这里用一个类统一传递public class PersonContext { private String personId; private String operator; private String reason; private String docType; private String bizCode; private String examResult; public PersonContext(String personId, String operator, String reason) { this.personId personId; this.operator operator; this.reason reason; } public String getPersonId() { return personId; } public String getOperator() { return operator; } public String getReason() { return reason; } public String getDocType() { return docType; } public void setDocType(String docType) { this.docType docType; } public String getBizCode() { return bizCode; } public void setBizCode(String bizCode) { this.bizCode bizCode; } public String getExamResult() { return examResult; } public void setExamResult(String examResult) { this.examResult examResult; } }这里把docType、bizCode、examResult都放进上下文是因为不同的转换规则需要不同的业务参数。状态机只负责读取这些字段并交给守卫判断不关心它们来自数据库还是前端请求。3.2 配置状态机转换规则使用 Spring Boot 时可以把状态机定义为一个 Bean。这样服务层可以Autowired注入也能在启动阶段直接校验转换表是否正确。import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class PersonStateMachineConfig { Bean public StateMachinePersonState, PersonEvent, PersonContext personStateMachine( AuditLogService auditLogService) { StateMachinePersonState, PersonEvent, PersonContext machine new StateMachine(); machine.addTransition(PersonState.FREE, PersonEvent.CAPTURE, PersonState.ARRESTED, context - context.getPayload().getReason() ! null !context.getPayload().getReason().isBlank(), context - auditLogService.record( context.getPayload(), PersonEvent.CAPTURE, 完成抓捕归档)); machine.addTransition(PersonState.ARRESTED, PersonEvent.DETAIN, PersonState.DETAINED, null, context - auditLogService.record( context.getPayload(), PersonEvent.DETAIN, 完成收容)); machine.addTransition(PersonState.DETAINED, PersonEvent.SENTENCE, PersonState.IMPRISONED, context - COURT_ORDER.equals(context.getPayload().getDocType()), context - auditLogService.record( context.getPayload(), PersonEvent.SENTENCE, 进入服刑状态)); machine.addTransition(PersonState.DETAINED, PersonEvent.REDEEM, PersonState.PROBATION, context - MERIT_REVIEW_PASSED.equals(context.getPayload().getBizCode()), context - auditLogService.record( context.getPayload(), PersonEvent.REDEEM, 戴罪立功审批通过)); machine.addTransition(PersonState.PROBATION, PersonEvent.GRADUATE, PersonState.SCHOOL, context - PASS.equals(context.getPayload().getExamResult()), context - auditLogService.record( context.getPayload(), PersonEvent.GRADUATE, 完成教育考核)); return machine; } }这里的配置和状态转换表一一对应。注意DETAINED状态配置了两个事件SENTENCE和REDEEM。这意味着同一个当前状态可以走两条不同的分支这正是状态机处理复杂业务的关键能力。3.3 服务层封装状态存储和事件触发状态机只负责判断和转移状态不负责保存状态。状态存储需要由业务服务层完成。这里先定义一个简单的存储接口便于后续替换成数据库实现。public interface CurrentStateStore { PersonState getCurrentState(String personId); void save(String personId, PersonState state); }学习环境可以使用内存实现import org.springframework.stereotype.Component; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; Component public class InMemoryCurrentStateStore implements CurrentStateStore { private final MapString, PersonState states new ConcurrentHashMap(); Override public PersonState getCurrentState(String personId) { return states.getOrDefault(personId, PersonState.FREE); } Override public void save(String personId, PersonState state) { states.put(personId, state); } }服务层封装完整的触发流程import org.springframework.stereotype.Service; Service public class PersonFlowService { private final StateMachinePersonState, PersonEvent, PersonContext stateMachine; private final CurrentStateStore currentStateStore; public PersonFlowService( StateMachinePersonState, PersonEvent, PersonContext stateMachine, CurrentStateStore currentStateStore) { this.stateMachine stateMachine; this.currentStateStore currentStateStore; } public PersonState fire(String personId, PersonEvent event, String operator, String reason) { PersonState current currentStateStore.getCurrentState(personId); PersonContext context new PersonContext(personId, operator, reason); PersonState next stateMachine.fire(current, event, context); currentStateStore.save(personId, next); return next; } }这里需要注意stateMachine.fire只负责返回目标状态真正提交状态变更的是currentStateStore.save。这一步分离非常重要因为业务动作中可能还要写日志、发通知、调用外部接口如果动作失败状态就不应该被保存。更严谨的做法是让整个fire过程在一个事务里执行后面会专门说明。3.4 模拟完整流程残虹入监珀塞特返校在测试代码或启动类中可以这样模拟两条完整路径。第一条路径是残虹的流程personFlowService.fire(RESHARD-001, PersonEvent.CAPTURE, admin, 发现违规行为); PersonContext detainContext new PersonContext(RESHARD-001, admin, 送往收容中心); personFlowService.fire(RESHARD-001, PersonEvent.DETAIN, admin, 完成收容评估); PersonContext sentenceContext new PersonContext(RESHARD-001, judge, 依法判决); sentenceContext.setDocType(COURT_ORDER); personFlowService.fire(RESHARD-001, PersonEvent.SENTENCE, judge, 进入服刑); PersonState state currentStateStore.getCurrentState(RESHARD-001); System.out.println(state); // IMPRISONED第二条路径是珀塞特的流程personFlowService.fire(PERCET-001, PersonEvent.CAPTURE, admin, 需要教育改造); personFlowService.fire(PERCET-001, PersonEvent.DETAIN, admin, 收容评估); PersonContext redeemContext new PersonContext(PERCET-001, committee, 戴罪立功审批); redeemContext.setBizCode(MERIT_REVIEW_PASSED); personFlowService.fire(PERCET-001, PersonEvent.REDEEM, committee, 审批通过); PersonContext graduateContext new PersonContext(PERCET-001, school, 考核合格); graduateContext.setExamResult(PASS); personFlowService.fire(PERCET-001, PersonEvent.GRADUATE, school, 考核完成); PersonState state currentStateStore.getCurrentState(PERCET-001); System.out.println(state); // SCHOOL如果跳过中间状态直接触发事件比如从ARRESTED直接触发GRADUATE状态机会抛出IllegalStateException提示“状态 ARRESTED 不允许事件 GRADUATE”。这就是把状态流转规则集中管理带来的第一个好处非法操作在入口处就被拦截。4. 验证、排错与生产环境落地4.1 用单元测试覆盖主干和异常分支状态机代码非常适合写单元测试因为输入是当前状态和事件输出是目标状态或异常。把下面的测试类放在src/test/java下使用 JUnit 5。import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertThrows; SpringBootTest class PersonFlowServiceTest { Autowired private PersonFlowService personFlowService; Autowired private CurrentStateStore currentStateStore; Test void shouldFlowFromFreeToSchool() { String personId PERCET-002; currentStateStore.save(personId, PersonState.FREE); personFlowService.fire(personId, PersonEvent.CAPTURE, admin, 需要教育改造); personFlowService.fire(personId, PersonEvent.DETAIN, admin, 收容评估); PersonContext redeemContext new PersonContext(personId, committee, 审批通过); redeemContext.setBizCode(MERIT_REVIEW_PASSED); personFlowService.fire(personId, PersonEvent.REDEEM, committee, 戴罪立功); PersonContext graduateContext new PersonContext(personId, school, 考核通过); graduateContext.setExamResult(PASS); personFlowService.fire(personId, PersonEvent.GRADUATE, school, 考核合格); assertEquals(PersonState.SCHOOL, currentStateStore.getCurrentState(personId)); } Test void shouldRejectInvalidEvent() { String personId RESHARD-002; currentStateStore.save(personId, PersonState.ARRESTED); assertThrows(IllegalStateException.class, () - personFlowService.fire( personId, PersonEvent.GRADUATE, admin, 不能直接返校)); } Test void shouldRejectWhenGuardNotPassed() { String personId RESHARD-003; currentStateStore.save(personId, PersonState.DETAINED); assertThrows(IllegalStateException.class, () - personFlowService.fire( personId, PersonEvent.SENTENCE, judge, 缺少法院文书)); } }测试通过之后才能基本确认状态转换表没有配错。注意测试要覆盖三类场景正常链路、非法事件、守卫拒绝。只测正常链路无法发现状态机配置里的隐藏问题。4.2 常见问题排查状态不更新、事件被忽略、并发覆盖状态机在实际项目中遇到的问题大多不是状态机本身的问题而是状态存储、并发控制或业务副作用的问题。下面是一张排查表。问题现象常见原因检查方式处理建议状态机提示“当前状态没有配置任何流转”状态存储中读到的当前状态不是预期值打印current状态检查前一步是否成功save确认状态写入时机必要时用审计日志追踪状态变化状态机提示“不允许事件”当前状态与该事件确实没有配置转换对照状态转换表检查业务顺序调整调用顺序或补充转换规则事件被调用两次动作执行两次事件没有幂等处理查看审计日志是否有重复记录在事件处理入口加唯一幂等键或使用状态版本号防止重复提交并发请求下状态错乱先读后写不是原子操作模拟两个线程同时触发事件使用数据库乐观锁或分布式锁守卫条件永远不通过上下文参数没有填充正确在日志中打印context的字段值确认调用方是否设置了docType、bizCode等参数排查时有一个通用原则先确认当前状态再确认事件再确认守卫条件最后确认动作是否执行。按照这个顺序排查大部分状态机问题都能在十分钟内定位。4.3 生产环境落地状态持久化、幂等、分布式锁和监控学习环境里使用内存Map保存状态很方便但生产环境必须替换成可靠存储。推荐的落地方式有三种在人员表中增加state字段用数据库唯一主键保证单条记录一致使用独立的事件流水表记录每一次“人员 事件 前后状态”方便追溯状态更新使用乐观锁例如UPDATE person SET state ?, version version 1 WHERE id ? AND version ?。幂等处理要在事件入口层做。每次调用都带一个requestId事件表对(personId, requestId)建唯一索引。重复请求插入失败后直接返回当前状态动作只执行一次。如果同一个人员可能被并发触发不同事件还需要加分布式锁。锁粒度尽量精确到personId不要用全局锁。简单实现可以基于数据库行锁SELECT * FROM person WHERE id ? FOR UPDATE;读取当前状态后再调用状态机最后执行UPDATE。这样可以把“读取当前状态 状态判断 状态更新”放到同一个事务中。监控方面至少要记录三个指标状态机调用次数状态机失败次数和失败原因每个状态的停留时长和转换时长。有了这些指标才能及时发现问题。比如某个人员长时间停留在DETAINED状态往往意味着后续事件没有被触发需要定时任务或人工介入。4.4 状态机设计检查清单这里整理一份可直接复用的检查清单项目上线前逐项核对。状态枚举是否覆盖所有业务状态是否存在从非法状态出发的转换规则每个合法转换是否都配置了守卫条件和动作非法转换是否会在状态机层被拒绝状态更新是否和动作在同一个事务中事件调用是否支持幂等是否记录了每次转换的前后状态和操作人并发场景下是否使用乐观锁或分布式锁是否覆盖正常链路、非法事件、守卫拒绝三类测试是否监控状态转换失败率和状态停留时长。这份清单不仅适用于本文的案例也适用于订单状态、审批流程、任务状态等常见业务场景。5. 从状态机到流程引擎下一步扩展方向手写轻量状态机适合业务规则清晰、状态数量可控的场景。当流程中引入人工审批节点、条件分支、并行网关、定时超时甚至需要可视化编排流程时可以考虑引入成熟的流程引擎比如 Flowable、Activiti 或 Spring StateMachine。状态机解决的是“状态能否转换”的问题流程引擎解决的是“流程如何推进”的问题。两者并不是二选一。在很多大型系统里核心业务状态仍然由状态机管理审批、会签、抄送等流程节点交给流程引擎处理最终再把流程结果回写到业务状态。回到本文的案例残虹和珀塞特的路径都可以看成一个流程抓捕、收容、审批、考核。只要把转换规则、守卫条件和动作定义清楚代码就具备可维护性。后续如果增加新状态比如“假释”或“社区矫正”只需要在状态枚举和转换表里增加对应配置不需要改动服务层的调用逻辑。建议动手练习时先不要急着引入框架。用本文的轻量状态机自己实现一遍把状态转换表、守卫条件、审计日志和并发问题都处理一遍再去看 Spring StateMachine 的源码理解会快很多。状态机设计最重要的不是记住某个框架的 API而是学会把业务规则表达成一张清晰的转换表。这张表能画清楚代码自然不容易写乱。