条件工作流的有类型写法：让分支判断在编译期就安全

条件工作流用多了之后，我最先想改造的不是执行引擎，而是条件本身的写法。很多人在做流程编排时，把分支判断当成“if/else 写进去就行”，结果一上批量任务就翻车：条件字段拼写错了不报错，分支返回结果在运行期才炸，换一个输入上下文所有判断全部失效。这里要聊的就是条件工作流的“有类型写法”，把工作流里的条件当成类型来建模，让编译器在运行之前就挡住一批低级错误。

这个主题适合正在写工作流引擎、业务流程编排、审批流、任务调度系统的人，也适合项目里已经出现“条件字段全靠字符串约定”这种写法的团队。最值得关注的不是某个具体框架，而是一整套可以迁移的建模思路：怎么把模糊的条件变成可检查的类型，怎么处理分支组合，怎么在类型安全之外继续排查运行期问题。

1. 条件工作流最常出问题的不是流程，而是条件的写法

1.1 无类型写法的三个典型痛点

先看最常见的一种写法。很多系统的条件判断长这样：

if (workflowContext.get("orderStatus") === "PAID") { // 走支付后流程 }

单看这一行，没毛病。但一旦整个工作流的节点多了，问题就开始积累。

第一个痛点：条件字段名只能靠记忆。orderStatus到底叫orderStatus还是order_status还是OrderStatus，代码里没有统一约束。有人写全大写，有人写驼峰，有人写小写下划线。工作流规模不大时，出错翻代码还能找到；规模大了以后，查一个字段来源要翻半天。

第二个痛点：字段值没有枚举约束。字符串比较是“写错不报错，运行期才炸”的重灾区。"PAID"写成了"PAID "，或者大小写不一致，比较结果永远为 false，但工作流不会提醒你，只会静默走进 else 分支。更麻烦的是，这种错误如果单元测试没覆盖到，往往要到生产环境某个订单卡住了才发现。

第三个痛点：分支结果之间没有类型关联。条件判断完之后，有的分支返回对象，有的分支返回数组，有的分支直接返回 null。下游节点拿到的到底是什么类型，完全靠人肉记忆。前端、API、消息队列哪一端拿错字段，都会出运行期错误。

1.2 有类型写法的核心价值

有类型写法要解决的就是这三件事：

• 条件字段名在编译期可检查，写错立刻报错，不用等到运行。
• 条件值有明确枚举或字面量类型，不会出现静默不匹配。
• 分支返回类型有约束，下游拿到的数据是确定的。

一句话总结：有类型写法的本质，是把“运行期才暴露的问题”提前到编码期。

理解这一点之后，下面所有设计原则都围绕它展开。类型不是给编译器看的装饰品，是给后来维护的人看的契约。

2. 环境与核心抽象：动手之前先准备什么

2.1 适用语言与运行时

条件工作流的有类型写法并不是某个框架的专利。只要语言支持类型系统，就能用。常见选择有这些：

下面代码以 TypeScript 为主，因为它的字面量类型和可辨识联合最直观。但这套思想可以平移到其他语言。原始材料没有限定具体框架，所以这里只讲通用做法，落地时以你们项目实际使用的语言和版本为准。

2.2 几个核心类型原语

在开始建模之前，先把几个原语理清楚。

枚举型条件

最基础的条件，就是一个字段取固定几个值：

type OrderStatus = "CREATED" | "PAID" | "SHIPPED" | "COMPLETED";

OrderStatus不再是一个普通 string。合法值被限定在四个字面量里。比较时写PAID，编译器能理解；写PAIDD，编辑器直接标红。这就是第一层保护。

布尔型条件

布尔型条件适合“是否满足某个前置条件”：

interface HasInvoice { hasInvoice: boolean; }

这类条件单独看不复杂，但组合起来容易失控。多个布尔条件叠加时，不能靠一堆&&硬拼，后面专门讲组合。

结构型条件

有时条件不是一个值，而是一组字段之间的约束：

interface DiscountEligible { userLevel: "NORMAL" | "VIP" | "SVIP"; orderAmount: number; couponUsed: boolean; }

结构型条件适合描述“这类上下文走这个分支”的规则。判断逻辑可以抽成纯函数，入参和返回都由类型约束。

3. 实操：把一个普通条件流程改成有类型写法

3.1 一个最常见的条件流程

现在假设要处理订单发货工作流。常规写法可能是这样：

function handleOrder(ctx: any) { if (ctx.status === "paid") { // 调用仓储 } else if (ctx.status === "canceled") { // 退款 } else { // 默认处理 } }

问题很集中：

• ctx是 any，字段名随便写，编译器完全不检查。
• status的值没有枚举，大小写、空格都可能造成隐式不匹配。
• 三个分支之间没有统一出口，返回结构不一致。

3.2 改造：用可辨识联合约束上下文

第一步，把上下文定义成可辨识联合：

type OrderEvent = | { type: "ORDER_PAID"; orderId: string; paidAt: string } | { type: "ORDER_CANCELED"; orderId: string; reason: string } | { type: "ORDER_SHIPPED"; orderId: string; trackingNo: string };

每个分支都有type字段作为判别标志。处理函数只需要：

function handleOrderEvent(event: OrderEvent) { switch (event.type) { case "ORDER_PAID": // 这里 TypeScript 能推导出 paidAt 存在 break; case "ORDER_CANCELED": // 这里能推导出 reason 存在 break; case "ORDER_SHIPPED": // 这里能推导出 trackingNo 存在 break; } }

这就是可辨识联合的价值：进入某个 case 之后，上下文里有哪些字段，编译器帮你锁定。不需要在代码里写一堆if (event.paidAt)做防御判断。

3.3 条件组合：别用一堆 if 堆叠

单个条件好写，组合条件才容易乱。比如这种业务规则：

• VIP 用户 + 订单金额大于 500 + 未使用优惠券，走满减分支。
• 非 VIP 用户 + 金额大于 500，走普通折扣分支。
• 其他情况，走默认分支。

老老实实写多个 if，后面维护时会很痛苦，因为条件之间的优先级完全靠阅读代码来理解。更稳的办法是把条件抽成显式规则类型：

interface DiscountRule { id: string; match: (ctx: OrderContext) => boolean; priority: number; }

然后把规则放到数组里按优先级执行：

const rules: DiscountRule[] = [ { id: "vip_high_value", match: isVipHighValue, priority: 10 }, { id: "normal_high_value", match: isNormalHighValue, priority: 20 }, ];

这样条件本身仍然是有类型的，规则顺序是显式数据，而不是藏在代码行号里的隐式逻辑。后面新增规则，只需要加一条DiscountRule，不需要改主流程。

4. 复杂场景：状态机、决策表与子流程条件

4.1 状态机与流转条件

条件工作流做到一定程度，就是状态机。每个状态节点能转移到哪些目标状态，就是一组条件。

有类型写法的状态机，一般长这样：

type OrderState = "CREATED" | "PAID" | "CANCELED" | "COMPLETED"; interface Transition { from: OrderState; to: OrderState; when: (ctx: OrderContext) => boolean; }

关键优势：from和to都被OrderState约束。新增状态时，如果Transition表格里没写全，编译器不会报错，但代码评审时能快速发现状态缺失。运行期还能加一层校验：遍历所有 Transition，保证每个状态都有出口，避免流程卡死。

实测经验：状态机的 bug 很少出在条件判断本身，更多出在“某个状态没有被任何 Transition 覆盖”。所以写完状态表以后，我一般会写一个单元测试，确认所有状态至少有一条可达路径。

4.2 决策表与规则类型

有些业务条件特别多，比如风控、审批、计费。多到用 if/else 根本写不动。这时候常见做法是决策表。

决策表在无类型写法里，通常是二维数组或者 JSON。有类型写法，可以把表的“行”定义成类型：

interface ApprovalRule { amountRange: [number, number]; userLevel: "NORMAL" | "VIP"; action: "APPROVE" | "REJECT" | "MANUAL_REVIEW"; }

然后通过查表函数找到匹配行，返回对应 action。amountRange用元组类型约束，userLevel用枚举约束，action也限定在三个值里。这样一来，配置表里写错一个字符串，编码期就能发现，不用等到某笔审批单跑出来才发现。

这里容易踩的坑是：决策表有顺序敏感。两条规则范围重叠时，命中的是第一条。所以规则数组最好显式带priority字段，不要让数组位置隐式决定优先级。位置一调整，行为就变，这种坑特别难排查。

4.3 子流程条件与上下文传参

当工作流有子流程时，条件往往要依赖父流程传下来的上下文。这时候类型要分两层：

• 父流程给子流程的输入，要有明确类型。
• 子流程回传的结果，也要有明确类型。

interface RefundSubflowInput { orderId: string; amount: number; reason: string; } type RefundSubflowOutput = | { ok: true; refundId: string } | { ok: false; errorCode: "BALANCE_NOT_ENOUGH" | "ACCOUNT_FROZEN" };

输出用可辨识联合表达成功与失败，而不是返回一个状态码 string。这样调用子流程的地方，拿到ok: false时，编译器会强制你处理errorCode，不会忘记错误分支。

5. 有类型也不是万能：边界与排查链路

5.1 编译期通过不等于运行期稳定

先泼一盆冷水：有类型写法能解决拼写错误、值域错误、分支返回类型混乱，但解决不了三类问题。

第一类：业务语义失效。类型是"PAID"不等于订单真的支付成功。状态更新到存储之间可能丢消息、被覆盖、重复消费。这些是运行期一致性问题，编译器管不了。

第二类：外部依赖异常。条件分支要查库存、查余额、调外部服务，返回值格式可能多变。类型声明只是你的预期，外部系统不遵守时，还是要靠运行期校验兜底。

第三类：类型被绕过。as any、反序列化接口、数据库返回字段，都可能绕过类型检查。只要数据是从 JSON 或数据库加载进来的，就要在边界做一次运行时校验或解析。

所以我的建议是：类型用在代码内部流转最有效，用在系统边界时要额外配校验。

5.2 常见报错与排查顺序

即使有了类型，运行期还是会遇到问题。按照我的习惯，排查顺序固定是：

1. 先看数据入口：上下文是从 API、MQ、数据库还是定时任务进来的？字段是不是被反序列化成了string或null？
2. 再看条件匹配：比较顺序、大小写、trim 有没有处理？数值范围是不是闭区间？空数组、0、空字符串会不会误命中？
3. 再看分支出口：走出分支之后，返回值喂给下游是否符合下游声明的类型？有没有返回undefined的情况？
4. 最后看规则顺序：决策表规则重叠时，是不是命中了一条优先级不是期望的规则？

这个顺序很重要。很多人一遇到工作流分支不对，先去翻流程配置，结果问题出在数据入口字段大小写不一致。数据不对，后面全错。

5.3 类型设计的边界

还有几个类型设计上的边界，值得单独说。

• 不要过度设计。像type A = "a" | "b"这种简单枚举够用，就别引入状态机框架。先解决眼前的问题。
• 不要在类型里塞运行时逻辑。类型只是编译期约束，不是执行逻辑。判断逻辑还是写函数，类型负责约束入参出参。
• 不要把条件字段散落各地。最好集中在上下文类型里，避免同一个业务字段在不同节点上有不同命名。
• 不要相信所有调用方都会遵守类型。团队成员可能为了省事写as any，代码评审时要盯住这个点。

6. 落地时我会怎么安排

如果团队现在还是无类型写法，我不会建议一步到位全部重写。更稳的顺序是这样。

6.1 第一步：给当前上下文字段加类型

先把所有ctx: any改成明确接口。这一步收益最大，成本最低。改完以后，IDE 提示和编译检查立刻生效，很多拼写类问题当场暴露。

6.2 第二步：把条件值改成枚举或字面量类型

把字符串比较的字段全部换成枚举类型。这一步能让“写错不报错”的问题大幅减少。改动范围通常集中在一个上下文文件里，不会牵动整个流程。

6.3 第三步：条件分支抽成规则类型

当单条流程里的 if 超过三个，或者多条流程共享同一套判断逻辑时，再把条件抽成规则数组。不要提前抽象。规则类型的维护成本比直接写 if 高，规则多了以后回报才明显。

6.4 第四步：跑通单条流程之后，再考虑批量与状态机

批量任务的坑和单条不同。单条跑通只表示某一组输入下流程正常。批量时需要考虑：条件字段缺失怎么办？重复消息怎么处理？规则匹配不到时走默认分支还是直接失败？

这些不是类型能解决的，但类型能让问题提前暴露。比如某个新的输入值没有枚举覆盖，编译器会提醒你决策表漏了一条，而不是等到生产环境出现未知状态。

6.5 留下一份检查清单

最后留一份我自己常用的检查清单：

• 条件字段名是否在类型中统一定义？
• 条件值是否为枚举或字面量类型？
• 分支返回类型是否一致，或者是否使用可辨识联合？
• 决策表规则顺序是否是显式 priority？
• 外部输入边界是否做了运行时校验？
• 每个状态是否有可达出口？
• 条件匹配失败时，是走默认分支还是显式报错？

踩过几次之后我发现，很多工作流问题不是引擎能力不够，而是前置环境和输入材料没有处理干净。有类型写法不能消除所有 bug，但它能把最容易犯的那一批错误，从生产环境拉回到编辑器里。先把单条流程跑稳，再谈批量和状态机，这个顺序不要反过来。