Skip to content

使用图表示流程与状态 ​

流程图描述一次任务如何向前执行,状态图描述一个对象在整个生命周期中允许处于什么条件。两种图都包含节点和连线,但建模对象、问题和验收方式不同。

  • 流程图回答:参与者下一步做什么,在哪个条件下分支,失败后回到哪里。
  • 状态图回答:对象当前是什么状态,什么事件能改变它,转移必须满足什么条件。
  • 时序图回答:多个参与者或系统按什么顺序交换消息。

一张图只承担一个主要问题。把页面、动作、对象状态、接口调用和数据库字段全部放进同一张图,会得到连线很多但无法实现和测试的“大图”。

一、先识别要建模的对象 ​

1. 任务流程 ​

任务流程以目标为起点,以可观察结果为终点。节点通常是:

  • 人的动作;
  • 系统动作;
  • 业务判断;
  • 等待外部结果;
  • 失败恢复;
  • 结束结果。

例如退款任务:

mermaid
flowchart TD
    A["买家提交退款原因和证据"] --> B["系统校验订单与申请期限"]
    B -->|不符合| C["返回具体原因与申诉入口"]
    B -->|符合| D["创建退款申请"]
    D --> E["商家审核"]
    E -->|同意| F["请求支付渠道退款"]
    E -->|拒绝| G["通知买家并开放申诉"]
    F -->|渠道受理| H["等待退款结果"]
    F -->|请求失败| I["保留申请并进入可重试队列"]
    H -->|成功| J["显示退款完成"]
    H -->|失败| I

该图说明“发生什么”,但不能单独回答退款申请现在是否合法、哪些状态允许取消或重复回调如何处理。

2. 领域对象状态 ​

状态是对象在一段时间内保持的业务条件,不是页面名称,也不是正在执行的函数。

退款申请可以有:

mermaid
stateDiagram-v2
    [*] --> pending_review: submit
    pending_review --> rejected: reject
    pending_review --> approved: approve
    pending_review --> cancelled: buyer_cancel
    approved --> refunding: provider_accept
    approved --> refund_failed: provider_reject
    refunding --> refunded: refund_succeeded
    refunding --> refund_failed: refund_failed
    refund_failed --> refunding: retry [retryable]
    rejected --> pending_appeal: appeal [within_deadline]
    pending_appeal --> approved: appeal_approved
    pending_appeal --> rejected_final: appeal_rejected
    refunded --> [*]
    cancelled --> [*]
    rejected_final --> [*]

状态图的每条边应能转成一条业务规则,而不是只起到视觉装饰作用。

3. 系统交互时序 ​

退款涉及产品服务、支付渠道和异步回调时,用时序图展开:

mermaid
sequenceDiagram
    actor Buyer as 买家
    participant API as 退款服务
    participant DB as 数据库
    participant Pay as 支付渠道

    Buyer->>API: POST /refunds + Idempotency-Key
    API->>DB: 创建 pending_review
    API-->>Buyer: 201 + refund_id
    Note over API,Pay: 审核通过后
    API->>Pay: 创建退款请求
    Pay-->>API: 已受理 provider_ref
    API->>DB: approved -> refunding
    Pay-->>API: 异步退款结果
    API->>DB: 按 provider_ref 去重并转移状态
    API-->>Buyer: 可查询最终状态

这张图说明消息顺序和同步、异步边界,但对象允许的全部转移仍以状态规则为准。

二、流程图的基本元素 ​

1. 起点和终点 ​

起点必须是可观察触发,例如“用户提交申请”“定时任务到期”“收到支付回调”。“进入系统”没有说明是谁、为何进入。

终点需要区分业务结果:

  • 成功完成;
  • 主动取消;
  • 不符合条件;
  • 可恢复失败;
  • 不可恢复失败;
  • 转人工处理;
  • 超时结束。

只有一个“结束”节点会丢失结果差异,也无法设计后续通知和指标。

2. 动作 ​

动作使用“主体 + 动词 + 对象”:

  • 管理员确认导入;
  • 系统校验文件;
  • 审批人拒绝申请;
  • 调度器重新执行任务。

“处理数据”“检查一下”“进行审核”没有明确输入和输出。系统动作还应在相邻规格中说明原子性:失败时是全部不写、部分写入,还是保留中间结果。

3. 判断 ​

判断节点必须是能够得到确定答案的条件:

text
申请是否仍在退款期限内?
当前角色是否具有 refund:approve 权限?
回调事件 ID 是否已经处理?
失败码是否允许自动重试?

每条出边应:

  • 标签互斥;
  • 覆盖所有可能结果;
  • 包含未知或数据缺失;
  • 指向具体动作或结果。

“是/否”只有在问题文字完整时才有意义。对于多值条件,应直接标记“可重试错误 / 永久错误 / 未知错误”,避免读图者不断返回判断节点寻找语义。

4. 泳道 ​

多个参与者共同完成任务时,用泳道明确责任:

泳道负责的动作不应承担的动作
买家提交、补充、撤销、申诉决定支付渠道真实结果
产品系统校验、授权、保存、通知伪造支付成功
商家审核人依据规则批准或拒绝绕过退款期限和权限
支付渠道接受请求并返回资金结果改写产品内审核原因
支持人员处理例外和申诉直接修改账务结果

当一条线跨越泳道时,需检查交接载荷、责任和超时。

5. 等待 ​

等待不是空白。应记录:

  • 等待什么事件;
  • 最长等待多久;
  • 期间对象处于什么状态;
  • 用户能否取消或离开;
  • 超时后怎样处理;
  • 重复事件怎样去重。

异步流程漏画等待节点,常导致界面把“已提交”显示成“已完成”。

6. 循环 ​

循环需要退出条件和次数边界:

mermaid
flowchart LR
    A["任务执行"] --> B{"结果类型"}
    B -->|成功| C["完成"]
    B -->|永久失败| D["停止并显示原因"]
    B -->|可重试且次数未满| E["指数退避并加入抖动"]
    E --> A
    B -->|次数已满| F["转人工或死信队列"]

“失败后重试”如果没有次数、间隔、幂等和停止条件,就不是完整规则。

三、状态机的基本元素 ​

1. 状态 ​

一个有效状态应满足:

  • 对象可以在其中停留;
  • 进入后有确定的允许操作;
  • 可以从持久数据或确定规则恢复;
  • 对监控、通知或权限有业务意义。

clicking_submit、calling_api 通常是短暂动作,不适合作为领域状态。pending_review、refunding、refunded 能决定后续行为,属于领域状态。

2. 事件 ​

事件是已经发生的事实:

  • refund_submitted
  • review_approved
  • provider_accepted
  • provider_reported_failure
  • appeal_deadline_reached

命令表达意图,如 approve_refund;事件表达结果,如 refund_approved。如果授权或业务条件不成立,命令可能被拒绝,不应产生成功事件。

3. 转移 ​

一条状态转移至少包含:

text
当前状态 + 触发事件 + 守卫条件 -> 新状态 + 副作用

可以写成规则表:

当前状态事件守卫条件新状态原子写入后续副作用
pending_reviewapprove有审核权限且金额未超限approved状态、审核人、时间、版本号请求支付渠道
pending_reviewreject有审核权限且原因非空rejected状态、原因、版本号通知买家
refundingprovider_success回调关联匹配且未处理refunded状态、渠道流水、事件去重键更新订单与通知
refund_failedretry错误可重试且次数未满refunding次数、下次执行时间加入任务队列

图提供整体结构,规则表保存图中不适合承载的详细条件。

4. 守卫条件 ​

守卫条件决定事件是否可以触发转移,例如:

  • amount <= reviewer_limit
  • current_version == expected_version
  • now <= appeal_deadline
  • error_code in retryable_codes

守卫失败后的行为必须确定:返回冲突、提示刷新、进入人工审核还是静默忽略。不能只写“条件不满足则不转移”,否则调用方无法恢复。

5. 初始、终止和吸收状态 ​

  • 初始状态说明对象创建时首先进入哪里。
  • 终止状态说明生命周期完成,通常不再接受业务转移。
  • 吸收状态是进入后只能保持自身的状态。

“已完成”不一定永远终止。例如结算完成后可能发生冲正。如果业务允许冲正,就应画出新事件和后续状态,而不是依赖管理员直接改库。

6. 复合与并行状态 ​

当一个对象同时拥有相互独立的状态维度,不要强行组合成大量枚举:

text
delivery_status: pending | shipped | delivered
payment_status: unpaid | authorized | captured | refunded

组合成 shipped_and_authorized、shipped_and_captured 会产生笛卡尔积。两个维度若有约束,用不变量连接,例如“发货前必须至少完成支付授权”。

只有当子状态共享清晰生命周期时才使用层级状态。过度嵌套会让团队无法判断实际活跃状态。

四、从流程中抽取状态机 ​

按以下步骤转换:

  1. 圈出流程中需要跨请求、跨设备或跨时间保存的对象。
  2. 找出会改变允许操作的稳定条件。
  3. 将动作改写为事件。
  4. 为每条事件标注合法来源状态。
  5. 写出守卫、目标状态和失败行为。
  6. 添加重复、乱序、超时、撤销和人工修复事件。
  7. 用规则表覆盖图中每条边。

例如“审核后调用支付并等待回调”可抽取为:

text
pending_review --approve--> approved
approved --provider_accept--> refunding
approved --provider_reject--> refund_failed
refunding --provider_success--> refunded
refunding --provider_failure--> refund_failed

approved 不能省略。如果调用支付前进程崩溃,系统需要知道审核已经成功但渠道请求尚未确认,从而安全恢复。

五、并发、重复和乱序 ​

1. 乐观并发 ​

两个审核人可能同时操作。命令应携带读取时的版本:

json
{
  "refundId": "rf_42",
  "command": "approve",
  "expectedVersion": 7
}

数据库更新条件为 id = rf_42 AND version = 7 AND state = pending_review。影响行数为 0 时返回冲突,并提供最新状态。不能让后写入者无声覆盖前一个决定。

2. 幂等 ​

网络超时后客户端无法知道第一次提交是否成功。对业务写操作,应使用业务唯一键或幂等键关联第一次结果。

幂等不代表每次响应字节完全相同,而是重复相同意图不会产生额外业务效果。退款请求不能因重复点击创建两次退款。

3. 重复回调 ​

外部系统可能重复发送同一事件。保存:

  • 渠道事件 ID;
  • 关联对象;
  • 载荷摘要;
  • 首次处理时间;
  • 处理结果。

去重记录和状态转移应在同一事务边界内,避免“状态已改但去重记录没写”。

4. 乱序回调 ​

若成功事件先于“受理”事件到达,不能把 refunded 倒退为 refunding。处理方式可以是:

  • 根据事件版本拒绝旧事件;
  • 只允许单调状态转移;
  • 暂存缺少前置事件的消息;
  • 向来源系统查询权威状态。

选择取决于外部协议是否提供序号、查询接口和最终一致性保证。

六、图与产品界面如何对应 ​

领域状态不应直接一对一映射为页面。一个页面可以展示多个对象状态,同一对象状态也可能在列表、详情和通知中出现。

建立表现映射表:

领域状态用户可见文案允许操作禁止操作恢复入口
pending_review等待商家审核撤销、补充材料重复提交查看预计时间
approved审核通过,正在提交退款查看详情再次审核联系支持
refunding退款处理中查看进度再次发起退款超时后查询
refund_failed退款未完成按原因重试或联系支持假装成功重试/支持
refunded退款完成查看流水修改金额申诉入口

前端的 loading、disabled、dialogOpen 是交互状态;服务端退款状态是领域事实。两者应分离,避免关闭弹窗就丢失正在处理的业务任务。

七、图怎样进入实现和测试 ​

1. 生成状态转移测试 ​

每条边至少有:

  • 合法来源状态成功转移;
  • 非法来源状态拒绝;
  • 守卫成立;
  • 守卫不成立;
  • 重复事件;
  • 并发版本冲突。

每个状态还需检查允许命令集合。只测试“快乐路径”无法证明状态机封闭。

2. 检查不可达状态和死路 ​

  • 是否存在从初始状态永远到不了的状态?
  • 是否存在非终止状态没有任何出边?
  • 是否存在只有失败才能进入、却没有恢复路径的状态?
  • 是否存在可以绕过授权或审核的捷径?
  • 是否存在无限循环且没有次数、时间或人工退出?

3. 对齐接口 ​

状态转移接口应表达意图,而不是允许调用方任意设置状态:

text
POST /refunds/{id}/approve
POST /refunds/{id}/reject
POST /refunds/{id}/cancel

比下面的接口更安全:

text
PATCH /refunds/{id} { "status": "refunded" }

后者把状态机规则泄露给客户端,也允许绕过支付结果。

4. 对齐事件与监控 ​

监控至少覆盖:

  • 各状态当前数量与停留时间;
  • 每条转移的成功、拒绝和冲突数量;
  • 超过服务时限的对象;
  • 重试次数和永久失败原因;
  • 重复与乱序事件;
  • 人工修复次数。

停留时间应从进入状态的可靠时间戳计算,而不是依赖页面打开时间。

八、版本演进 ​

状态机上线后仍会变化。新增状态时要处理:

  1. 旧记录如何映射;
  2. 新旧服务版本并存时接受哪些状态;
  3. 进行中的工作流是否迁移;
  4. 回滚代码能否读取新状态;
  5. 数据仓库和看板是否认识新枚举;
  6. 客服工具能否解释新状态;
  7. 外部 API 是否暴露稳定兼容值。

删除状态不等于删除枚举值。数据库、历史事件和外部消费者可能长期保存旧值。可以停止产生旧状态,但读取路径仍需定义兼容行为。

九、常见错误 ​

把页面当状态 ​

错误:list_page -> detail_page -> success_page。

页面变化不能说明对象是否合法或是否完成。应分别画用户导航和领域对象状态。

把动作当状态 ​

错误:clicking -> validating -> calling_api。

这些是瞬时执行步骤。只有需要持久恢复或决定允许操作时,才提升为业务状态,例如 awaiting_provider_result。

只画成功路径 ​

网络失败、权限变化、对象被删除、重复提交、超时和取消都是流程的一部分。缺失并不意味着实现不会遇到。

用线条代替规则 ​

一条 pending -> completed 的线没有触发事件、守卫与副作用,无法形成接口和测试。

让图成为过期副本 ​

状态枚举改动时应在同一个变更中更新图、规则表、测试和事件字典。图若无法与代码共同评审,很快会失去可信度。

十、评审清单 ​

流程图 ​

  • [ ] 起点是具体触发,终点区分不同业务结果。
  • [ ] 动作写明主体、动词和对象。
  • [ ] 判断分支互斥、完备,并处理未知数据。
  • [ ] 跨参与者交接标明载荷、责任和超时。
  • [ ] 等待、重试、取消和人工恢复已经画出。
  • [ ] 循环有次数、时间或业务退出条件。

状态图 ​

  • [ ] 状态是可停留、可恢复、影响允许行为的条件。
  • [ ] 命令和事件没有混用。
  • [ ] 每条转移有来源、事件、守卫、目标和失败行为。
  • [ ] 初始、终止、并行和层级关系明确。
  • [ ] 重复、并发、乱序和过期事件有规则。
  • [ ] 不存在未解释的不可达状态或非终止死路。

落地 ​

  • [ ] 图中每条边能追溯到需求、接口或验收测试。
  • [ ] 界面文案与操作由领域状态映射,而非直接等同。
  • [ ] 监控可以发现长时间停留和非法转移。
  • [ ] 状态新增、删除和回滚有数据兼容方案。
  • [ ] Mermaid 图在 Obsidian 和 GitHub 中能够正常渲染。

来源 ​

从前端走向软件产品工程的长期路线图。