跳到正文
D2-01交易域2 分钟更新于 2026-11

状态机设计

一句话

状态机不是"枚举几个状态",而是定义什么事件、在什么前置条件下、能把状态推到哪,以及推不动时怎么办。

本文目录10 节

状态机设计

先看一个错误示范

// 大量系统的真实写法
await db.update('transactions', { id }, { status: 'succeeded' })

问题不在代码好坏,在于它允许:

  • 已成功的单被改成失败
  • 已退款的单被改成成功
  • 渠道返回一个没见过的字符串,直接落库,统计口径当场崩掉

这三个口子,每一个都会在半年内以"账对不上"的形式暴露。

状态集合:分成两组,不要塞进一个字段

支付和退款是两条独立的生命周期,共用一个 status 字段是灾难的开始。

组状态说明
支付生命周期created → processing → succeeded / failed / closed终态:succeeded / failed / closed
退款生命周期refunding → refunded / partially_refunded / refund_failed可以多次,所以是累计状态
正在绘制图表…

关键点:unknown 必须是一个正式状态,不是异常。 渠道超时、回调没到、报文解析失败——这时候你既不能说成功也不能说失败。 不给它一个名字,它就会伪装成 failed,然后被正确支付掉的钱就成了"丢失的客户"。

三条不可违反的规则

规则一:终态不可回退

succeeded 不能被改成 failed。如果真错了(比如误判),要新增一条冲正记录, 而不是修改原记录。因为原记录是"当时发生了什么"的事实,事实不能篡改。

规则二:状态只能由事件驱动

每次迁移必须有一条事件(渠道回调 / 查单结果 / 人工操作),事件要落库。 只有当前状态、没有事件流,出问题时你会知道"现在是 succeeded",但不知道"为什么"。

规则三:渠道状态必须过映射,不允许直接落库

const MAP = {
  created: 'processing', pending: 'processing',
  success: 'succeeded', succeeded: 'succeeded',
  failed: 'failed', closed: 'closed',
}
const map = (s) => MAP[String(s).toLowerCase()] ?? 'unknown'

永远保留一个 unknown 兜底。渠道加了一个新状态而你不知道, 最坏的结果是"归类为 unknown 等人工处理",而不是"污染了成功率统计"。

迁移校验:写在一处,别散在业务里

const ALLOWED = {
  created:    ['processing', 'closed'],
  processing: ['succeeded', 'failed', 'unknown'],
  unknown:    ['succeeded', 'failed'],
  succeeded:  ['refunding'],
  refunding:  ['refunded', 'partially_refunded', 'failed'],
  failed: [], closed: [], refunded: [], partially_refunded: [],
}

function assertTransition(from, to) {
  if (!(ALLOWED[from] || []).includes(to)) {
    throw new Error(`非法状态迁移 ${from} → ${to}`)
  }
}

放在数据库约束或统一 service 里都行,但只能有一处。 散在业务代码里的结果,是每加一个功能就漏一个口子。

一个容易被忽略的点:状态和"金额"必须一致

部分退款后,status = partially_refunded 但 refunded_amount 必须同步。 这两个字段不一致,是对账差异的常见来源。

更稳的做法:状态由金额推导,而不是单独维护。

refunded_amount == 0        → 不退
0 < refunded_amount < total → partially_refunded
refunded_amount == total    → refunded

自查清单

  • unknown 是正式状态,且有对外展示文案(不是内部错误码)
  • 退款状态独立于支付状态
  • 终态有守护,任何代码路径都改不动
  • 渠道状态有映射表 + 未知兜底
  • 每次迁移有事件记录(谁、何时、依据什么)
  • 状态与累计金额可以互相校验

依据

  • 支付行业的通用实践:状态即契约,契约不可回退
  • 卡组织授权/请款/撤销的时序本身是单向的
相关阅读