状态机并不是新概念，从编译器词法分析到游戏角色AI都能看到它的身影。在TypeScript项目里，如果把状态转移写成散落的if-else或switch，随着业务状态增多，很容易出现非法状态跳转，例如订单从已取消直接变成已发货。要杜绝这类问题，光靠团队约定不够，最好把状态转移规则交给类型系统。TypeScript的字符串字面量联合类型和泛型约束正好能做这件事。本文会实现一个严格的有限状态机，确保每次状态转移都符合预定义的转移表。
用联合类型定义状态与事件
先定义状态和事件的集合。假设我们要描述一个订单状态机，订单可以处于待支付、已支付、已发货、已完成和已取消五种状态。事件包括支付、发货、完成和取消。用字符串字面量联合类型可以精确表达这些有限集合。
type OrderState = 'pending' | 'paid' | 'shipped' | 'completed' | 'cancelled'; type OrderEvent = 'PAY' | 'SHIP' | 'COMPLETE' | 'CANCEL';
字符串字面量联合类型的好处是编译器能识别所有合法值，任何拼写错误都会在开发阶段暴露。比如把状态写成 'pendin'，TypeScript会直接报错，而普通字符串类型则不会。但这还远远不够，因为联合类型只告诉我们可以有哪些状态和事件，并没有规定哪些事件在哪些状态下合法。比如待支付状态下直接触发完成事件，从业务角度看就是非法跳转。因此下一步需要把转移规则也编码到类型里。
我们可以用映射类型来构建转移表。上例中，每个状态作为一个键，值为一个对象，该对象的键是允许的事件，值是对应的目标状态。代码如下所示。
type StateTransitions = {
pending: { PAY: 'paid'; CANCEL: 'cancelled' };
paid: { SHIP: 'shipped'; CANCEL: 'cancelled' };
shipped: { COMPLETE: 'completed' };
completed: Record<string, never>;
cancelled: Record<string, never>;
};
这里 completed 和 cancelled 状态用 Record<string, never> 表示没有任何允许的事件。这样转移表就清晰地描述了整个状态机的合法路径：待支付只接受支付和取消，已支付只接受发货和取消，已发货只接受完成。任何不在表中的转移都是非法的。接下来要实现一个状态机类，在实际执行转移时借助这张表进行约束。
实现状态机类并约束转移方法
第一种实现方式是用一个可变类来封装当前状态，并提供 transition 方法。这个方法接收事件名，并查找转移表，如果找到目标状态就更新，否则抛出异常。为了获得编译期提示，事件参数类型可以限定为当前状态允许的事件联合。不过可变类中当前状态类型的动态变化无法用简单的泛型表达，所以事件参数会放宽为所有状态允许的事件联合。代码如下。
class OrderStateMachine {
private state: OrderState;
constructor(initial: OrderState) {
this.state = initial;
}
get current(): OrderState {
return this.state;
}
transition(event: keyof StateTransitions[OrderState]): void {
const transitions = StateTransitions[this.state] as Record<string, OrderState>;
const target = transitions[event as string];
if (!target) {
throw new Error('Illegal transition from ' + this.state + ' via ' + event);
}
this.state = target;
}
}
这段代码中，事件参数的类型是 keyof StateTransitions[OrderState]，它是 'PAY' | 'SHIP' | 'COMPLETE' | 'CANCEL' 的并集，编译期可以防止传入完全不存在的事件，比如 'REFUND'。但无法根据当前状态精确缩小事件范围，因此运行时仍要检查目标值是否存在，并抛出异常。这是可变状态机常见的折中方案。
如果希望获得更严格的编译期检查，可以让状态机不可变，每次转移返回一个新实例，并把状态作为类型参数。这样每个实例的类型都携带当前状态信息，事件参数就可以精确限制为该状态下允许的事件。实现方式如下。
type StateMachine<S extends OrderState> = {
readonly state: S;
send<E extends keyof StateTransitions[S]>(event: E): StateMachine<StateTransitions[S][E]>;
};
function createMachine<S extends OrderState>(initial: S): StateMachine<S> {
return {
state: initial,
send(event) {
const transitions = StateTransitions[this.state] as Record<string, OrderState>;
const nextState = transitions[event as string];
if (!nextState) {
throw new Error('Illegal transition');
}
return createMachine(nextState as StateTransitions[S][typeof event]);
}
};
}
这个版本里，send 方法的泛型 E 被约束为 keyof StateTransitions[S]，也就是当前状态允许的事件集合。如果当前状态是 'pending'，那么事件只能是 'PAY' 或 'CANCEL'，尝试传入 'SHIP' 会在编译期直接报错。转移后返回的新实例类型是 StateMachine<StateTransitions[S][E]>，比如从 'pending' 支付后得到 StateMachine<'paid'>。这种模式把大部分校验前移到了编译期，代价是对象会不断创建，状态管理需要遵循不可变原则。
用never类型和穷尽检查强化转移限制
状态机实现后，还需要保证转移表本身是完整的。随着业务变化，新增状态或事件时很容易遗漏更新。TypeScript的 never 类型可以帮助做穷尽检查。通常我们会写一个 assertNever 函数，然后在 switch 语句的 default 分支中调用它。如果漏掉了某个状态，编译会报错。
function assertNever(value: never): never {
throw new Error('Unexpected state: ' + value);
}
function describeState(state: OrderState): string {
switch (state) {
case 'pending':
return '待支付';
case 'paid':
return '已支付';
case 'shipped':
return '已发货';
case 'completed':
return '已完成';
case 'cancelled':
return '已取消';
default:
return assertNever(state);
}
}
assertNever 的参数类型是 never，只有穷尽了所有可能状态，state 在 default 分支才会被类型收窄为 never。如果将来给 OrderState 增加了 'refunded'，而 switch 没有处理，default 分支的 state 类型就不兼容 never，编译器会提示错误。这样团队就能及时发现转移表或相关逻辑需要补充。
除了编译期穷尽检查，状态转移条件往往还包含运行时守卫。例如支付成功后才能发货，除了状态正确，还需要检查支付金额或库存。可以在状态机外部创建守卫函数，或者在 transition 方法中接受额外的守卫回调。守卫返回 false 时阻止转移并抛出异常。这样就把业务规则和状态转移表解耦，状态机本身保持简单，复杂条件由业务层处理。
实际场景与注意事项
在实际项目中，状态机通常用于订单、工单、审核流等场景。把状态转移表独立出来作为单一数据源，可以让产品、后端、前端共享同一份规则，减少沟通成本。TypeScript的类型定义可以生成文档，帮助新成员快速理解状态流转路径。如果状态数量很多，建议使用专门的库如XState，它支持状态图、嵌套状态、并行状态和副作用，但引入前要评估项目复杂度。如果只是简单的线性流转，手写一个类型安全的状态机完全足够。
需要注意的是，状态机虽然限制了转移，但并不能解决所有业务问题。比如并发情况下两个请求同时触发转移，可能都通过了检查，导致状态被覆盖。面对并发场景，需要结合数据库行锁、乐观锁或事件溯源来保证一致性。另外状态机的设计要尽量简单，避免过度抽象，否则维护成本反而上升。状态和事件命名应该清晰，转移表要集中管理，避免分散在不同模块。
回到TypeScript实现本身，类型系统的限制越强，开发体验越好，但也要留意类型体操的复杂度。本文展示的不可变状态机方案适合状态数量不多、转移路径清晰的场景。如果状态爆炸式增长，类型推导可能变慢，此时可以退回到运行时检查为主的方案，并配合单元测试覆盖所有转移路径。无论采用哪种方式，核心目标都是把非法状态跳转消灭在开发阶段，而不是等到线上出现数据异常。
TypeScript状态机状态转移限制有限状态机修改时间：2026-10-03 10:46:42