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是正式状态,且有对外展示文案(不是内部错误码) - 退款状态独立于支付状态
- 终态有守护,任何代码路径都改不动
- 渠道状态有映射表 + 未知兜底
- 每次迁移有事件记录(谁、何时、依据什么)
- 状态与累计金额可以互相校验
依据
- 支付行业的通用实践:状态即契约,契约不可回退
- 卡组织授权/请款/撤销的时序本身是单向的
相关阅读