条件工作流是开发过程中最常见、也最容易失控的一种逻辑形态。一开始你可能只是在业务代码里加一个分支判断几个月之后那段代码就会变成一串没人敢动的字符串状态和 if-else 嵌套。这篇文章想讲清楚一个判断条件工作流的复杂度从来不在“流程图画得多漂亮”而在“状态流转的约束是否被编译器兜住”。把散落的字符串状态换成字面量联合类型把分支条件收敛成带签名的守卫函数这种写法就叫“有类型写法”。读完本文你会理解条件工作流为什么容易腐化也能拿到一份完整可运行的 TypeScript 示例在内容审核发布、订单流转、Agent 工具链选择等场景中直接复用这套思路。1. 这篇文章真正要解决的问题很多开发者在项目中会天然地实现“条件工作流”用户提交内容后系统根据内容长度、敏感词命中结果、审核人操作来决定下一步。状态可能是draft、submitted、approved、rejected、published流转条件是若干if判断。这种写法在节点少的时候非常直观一旦节点增多问题就会集中爆发。最典型的场景有三类第一类是内容平台的内容审核流程。一条内容要经过草稿、提交、审核、驳回、发布中间还有重新编辑和重复提交。如果不加约束状态与状态之间可以任意跳转draft直接变published这种非法路径在运行时才暴露。第二类是电商或后端系统的订单流转。待支付、已支付、已发货、已签收、已退款不同状态对参数有完全不同的要求。无类型写法里状态是字符串参数是MapString, Object任何状态都能携带任何参数编译器完全帮不上忙。第三类是 Agent 或 LLM 应用中的任务编排。工具调用、条件分支、人工确认任何一个环节写错条件整个流程都会走偏而且错误往往要到真实任务执行时才出现。这三类场景的共同痛点是状态本身是分散的字符串流转条件没有类型签名错误发生的时间点被推迟到了运行时。有类型写法做的事情就是把这三种风险全部提前到编译期。所以这篇文章适合的读者很明确正在用 TypeScript、Java 或其他静态类型语言编写审批流、状态机、流程编排、Agent 工具链的开发者以及维护过复杂 if-else 流程、想找一种可维护方案的技术负责人。2. 条件工作流的基础概念与常见误区2.1 什么是条件工作流条件工作流可以拆成两个词理解工作流是一组节点和节点间的转移关系条件则决定了转移是否发生。节点在业务里叫“状态”转移在代码里通常体现为“状态变更”条件是“守卫函数”。举个例子一个简化版的内容审核流程状态草稿、待审核、已通过、已驳回、已发布事件提交审核、审核通过、审核驳回、发布条件内容长度是否达标、审核结论是否为通过用伪代码描述一次提交动作if (content.length 20 status draft) { status submitted; }这个逻辑本身不复杂但它把“状态判断”和“业务条件”混在一起并且status只是一个字符串。如果项目里同时有十几个这样的判断代码就会变成一张谁也看不懂的状态蜘蛛网。2.2 无类型写法的典型代码很多项目最初的工作流代码长这样type Status string; interface ReviewContext { contentId: string; content: string; approveResult?: boolean; } function canSubmit(ctx: ReviewContext, status: Status): boolean { return status draft ctx.content.trim().length 20; } function nextStatus(status: Status, ctx: ReviewContext): Status { if (status draft canSubmit(ctx, status)) { return submitted; } if (status submitted ctx.approveResult true) { return approved; } if (status submitted ctx.approveResult false) { return rejected; } return status; }这段代码的优点是短缺点是三个层面都缺乏保护Status是string写错一个字母比如sumitted编译器完全无感。nextStatus可以返回任意字符串draft到published也能通过编译。ctx.approveResult是一个可选字段submitted状态下读取它没问题但draft状态下也能读到类型系统无法表达“某些字段只在某状态下存在”。这些缺陷在代码量小的时候不算致命但随着分支增加每次重构都要靠人肉搜索字符串每次上线都要祈祷没有漏掉某个状态组合。2.3 三个常见误区误区一状态只是一个字符串。状态是流程模型的骨架应该用类型把它约束起来而不是放任它变成任意字符串。误区二条件只是 if-else。条件函数应该是流程模型的一等公民它有明确的输入和输出也应该有明确的类型签名。误区三类型只用于数据建模不用于流程建模。类型系统不仅能描述“一个对象有哪些字段”还能描述“一个流程允许哪些跳转、每个跳转需要什么参数”。维度无类型写法有类型写法状态定义type Status stringdraft | submitted | ...非法跳转运行时才发现编译期直接报错条件参数松散、任意函数签名强约束新增状态引发连锁 if 修改编译器提示所有分支重构安全性依赖人工排查编译器兜底3. 有类型写法的核心思路有类型写法的本质是把流程模型变成编译器可理解的约束。具体来说有四层思路。3.1 用字面量联合类型约束状态集合第一步是让状态从一个无限字符串集合缩小到一个有限联合类型export type WorkflowStatus | draft | submitted | approved | rejected | published;从此之后任何WorkflowStatus类型的变量只能取这五个值。写错拼写编译器会立刻报错。3.2 用映射类型约束合法跳转光是约束状态集合还不够还需要约束“从 A 状态能跳到哪些状态”。在 TypeScript 里可以用一个映射接口表达export interface TransitionMap { draft: submitted; submitted: approved | rejected; approved: published; rejected: draft | submitted; published: never; }never表示该状态没有任何合法去向。这样draft只能跳到submittedapproved只能跳到published所有非法跳转都会在编译期被拒绝。3.3 用泛型守卫函数把条件签名化条件不再是散落的 if 判断而是一个有明确签名的守卫函数export type ConditionCtx (ctx: Ctx) boolean;流转规则把“来源状态、目标状态、守卫条件”绑定在一起export interface TransitionRule S extends keyof TransitionMap, Ctx { from: S; to: TransitionMap[S]; condition: ConditionCtx; description?: string; }这里的关键在于to的类型取决于from。如果from是draft那么to只能是submitted想写成published都过不了编译。3.4 用穷尽性检查兜底当状态集合扩展时所有处理状态的switch都应该有一个兜底分支调用一个never函数export function assertNever(value: never): never { throw new Error(非法状态: ${JSON.stringify(value)}); }这样做的好处是以后新增一个状态switch中如果没有新增对应case编译器会通过assertNever的参数类型不匹配来提醒开发者。流程模型扩展时所有需要修改的地方都会被编译器标出来。这四层思路合在一起流程错误就从“运行时猜谜”变成了“编译期提示”。这就是有类型写法最核心的价值。4. 环境准备与前置条件本文示例使用 TypeScript需要 Node.js 环境和 TypeScript 编译器。建议使用 Node.js 的长期支持版本TypeScript 使用 5.x 及以上版本具体小版本以安装时为准示例代码不依赖特定小版本特性。创建项目并安装依赖mkdir typed-workflow cd typed-workflow npm init -y npm install typescript types/node --save-dev初始化 TypeScript 配置npx tsc --init将tsconfig.json核心配置调整如下{ compilerOptions: { target: ES2020, module: CommonJS, rootDir: src, outDir: dist, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true }, include: [src] }strict必须开启。有类型写法的价值建立在严格类型检查的基础上如果关闭strictundefined、空值、联合类型相关的保护都会失效。在package.json中添加脚本{ scripts: { build: tsc, start: npm run build node dist/demo.js } }目录结构规划如下typed-workflow/ ├── src/ │ ├── types.ts │ ├── conditions.ts │ ├── engine.ts │ └── demo.ts ├── package.json └── tsconfig.json5. 完整示例内容审核发布工作流示例场景是一条内容从草稿到发布的完整审核流程包含提交、审核通过、审核驳回、驳回后重新提交、最终发布五个节点。状态定义、流转规则、业务条件、执行引擎分离在四个文件中。5.1 定义状态与上下文文件路径src/types.ts// 状态集合程序里只有这五种状态是合法的 export type WorkflowStatus | draft | submitted | approved | rejected | published; // 合法跳转表key 是来源状态value 是允许的目标状态集合 export interface TransitionMap { draft: submitted; submitted: approved | rejected; approved: published; rejected: draft | submitted; published: never; } // 流程上下文存储内容信息和审核结果 export interface ReviewContext { contentId: string; author: string; content: string; submittedAt?: string; reviewedBy?: string; approveResult?: boolean; publishAt?: string; } // 守卫条件接收上下文返回是否允许流转 export type ConditionCtx (ctx: Ctx) boolean; // 流转规则从哪个状态来、到哪个状态去、满足什么条件 export interface TransitionRule S extends keyof TransitionMap, Ctx extends ReviewContext { from: S; to: TransitionMap[S]; condition: ConditionCtx; description?: string; } // 穷尽性检查兜底函数 export function assertNever(value: never): never { throw new Error(非法状态: ${JSON.stringify(value)}); } // 状态的中文标签用于日志输出 export function getStatusLabel(status: WorkflowStatus): string { switch (status) { case draft: return 草稿; case submitted: return 待审核; case approved: return 已通过; case rejected: return 已驳回; case published: return 已发布; default: return assertNever(status); } }TransitionMap是这套设计的关键。它描述了流程层面的业务规则比如draft只能去submittedrejected可以退回draft也可以重新提交到submitted。状态流转规则集中维护在这一个接口里后续新增状态或调整流程只需要修改这一处。getStatusLabel中的default分支使用了assertNever。如果以后在WorkflowStatus中增加一个新状态而这里没有补充对应caseassertNever(status)的调用就会触发编译错误因为此时status的类型不再是never。5.2 定义业务条件文件路径src/conditions.tsimport { Condition, ReviewContext } from ./types; // 内容达到一定长度后才允许提交审核 export const hasEnoughContent: ConditionReviewContext (ctx) { return ctx.content.trim().length 20; }; // 审核结论为通过 export const isApproved: ConditionReviewContext (ctx) { return ctx.approveResult true; }; // 审核结论为驳回 export const isRejected: ConditionReviewContext (ctx) { return ctx.approveResult false; }; // 审核通过后默认允许发布 export const canPublish: ConditionReviewContext () { return true; };条件函数全部是纯函数不修改上下文只根据输入返回布尔值。这样做的好处是方便单元测试给一个确定上下文必然得到确定结果。canPublish虽然直接返回true但在真实项目中可以在这里加入发布窗口时间、敏感词复核等逻辑而不需要改动引擎。5.3 实现类型安全执行引擎文件路径src/engine.tsimport { ReviewContext, TransitionMap, TransitionRule, WorkflowStatus } from ./types; export class WorkflowEngineCtx extends ReviewContext { private rules: Array TransitionRulekeyof TransitionMap, Ctx []; // 添加流转规则S 会根据 from 字段被自动推断 addRuleS extends keyof TransitionMap( rule: TransitionRuleS, Ctx ): void { this.rules.push(rule); } // 执行一次状态流转遍历所有规则找到来源匹配且条件满足的规则 run(current: WorkflowStatus, ctx: Ctx): WorkflowStatus { for (const rule of this.rules) { if (rule.from current rule.condition(ctx)) { this.logTransition(current, rule.to, rule.description); return rule.to; } } return current; } private logTransition( from: WorkflowStatus, to: WorkflowStatus, description?: string ): void { const reason description ?? 无描述; console.log([流转] ${from} - ${to}, 原因: ${reason}); } }引擎本身很短但它包含了重要的类型约束addRule的from和to必须在同一个规则内匹配。当调用方写from: draft时to的类型会自动收窄为submitted这在编译期就杜绝了“草稿直接发布”这类非法流转。run方法按注册顺序遍历规则因此规则的注册顺序也是一种配置。在条件互斥的情况下顺序不影响结果如果条件可能同时满足则需要明确规则的优先级。5.4 组装工作流并执行文件路径src/demo.tsimport { WorkflowEngine } from ./engine; import { ReviewContext, WorkflowStatus } from ./types; import { hasEnoughContent, isApproved, isRejected, canPublish } from ./conditions; const ctx: ReviewContext { contentId: post-001, author: zhangsan, content: 这是一篇关于条件工作流有类型写法的技术分享文章。, submittedAt: new Date().toISOString(), approveResult: true }; const engine new WorkflowEngineReviewContext(); engine.addRule({ from: draft, to: submitted, condition: hasEnoughContent, description: 内容长度达到要求提交审核 }); engine.addRule({ from: submitted, to: approved, condition: isApproved, description: 审核通过 }); engine.addRule({ from: submitted, to: rejected, condition: isRejected, description: 审核驳回 }); engine.addRule({ from: approved, to: published, condition: canPublish, description: 允许发布 }); let status: WorkflowStatus draft; console.log(初始状态: ${status}); status engine.run(status, ctx); console.log(当前状态: ${status}); status engine.run(status, ctx); console.log(当前状态: ${status}); status engine.run(status, ctx); console.log(当前状态: ${status});这里有意没有注册rejected到draft的规则因为示例中审核结论是true流程走的是通过分支。把approveResult改为false流程就会停在rejected状态方便观察条件分支效果。如果尝试注册一条非法规则比如从draft直接跳到published// 这行代码无法通过编译 // Type published is not assignable to type submitted engine.addRule({ from: draft, to: published, condition: hasEnoughContent });类型系统会直接拦截这种错误而不是等程序运行到某一步才崩溃。6. 运行结果与效果验证6.1 编译运行在项目根目录执行npm start程序会先执行tsc编译再运行编译产物。预期输出如下初始状态: draft [流转] draft - submitted, 原因: 内容长度达到要求提交审核 当前状态: submitted [流转] submitted - approved, 原因: 审核通过 当前状态: approved [流转] approved - published, 原因: 允许发布 当前状态: published说明整条正常路径已经跑通。值得注意的是[流转]日志说明run每执行一次只推进一个状态调用三次后流程到达终点published。6.2 验证非法流转被编译拦截把demo.ts中合法的approved到published规则改成draft到publishedengine.addRule({ from: draft, to: published, condition: hasEnoughContent, description: 非法规则 });重新执行npm start编译阶段就会报错src/demo.ts:36:7 - error TS2322: Type published is not assignable to type submitted.这个报错比任何运行时日志都值钱错误发生在开发环境而不是生产环境。这就是有类型写法最直观的效果验证。6.3 验证逻辑正确性除了编译通过还可以做一个“分支切换”实验。把ctx.approveResult改为falseconst ctx: ReviewContext { contentId: post-002, author: lisi, content: 这是一篇会被驳回的内容用于验证审核不通过分支。, submittedAt: new Date().toISOString(), approveResult: false };再次运行预期输出初始状态: draft [流转] draft - submitted, 原因: 内容长度达到要求提交审核 当前状态: submitted [流转] submitted - rejected, 原因: 审核驳回 当前状态: rejected流程正确走到了rejected因为isApproved返回false而isRejected返回true。这说明条件守卫在运行时的逻辑也是正确的类型安全没有牺牲业务灵活性。7. 常见问题与排查思路问题现象可能原因排查方式解决方案类型报错信息复杂难以定位TransitionMap映射关系过深TS 提示包含多层推断先看报错的第一行定位具体文件与行号把复杂规则拆成独立函数或使用TransitionRule显式标注类型条件需要访问异步接口Condition是同步函数无法直接等待请求结果检查守卫函数是否有异步操作在进入run之前先异步加载数据并写入ReviewContext保持条件同步驳回后再次提交流程不一致rejected状态没有注册后续规则打印当前状态观察停在哪个节点为rejected补上draft或submitted的合法跳转规则团队不熟悉类型写法维护困难项目其他部分仍在使用无类型模式从状态定义和规则表开始讲解渐进式改造先替换字符串状态再逐步引入条件守卫运行时规则与类型定义不一致引擎规则在运行时被动态修改绕过了类型约束检查代码中是否有as强制类型转换增加不可变规则设计禁止运行时修改规则列表其中最容易踩坑的是第一条。TypeScript 的类型推断在泛型嵌套时会产生很长的报错信息但只要把from类型写清楚绝大多数错误都会在addRule调用处直接暴露为“目标状态不匹配”可读性已经比无类型写法好很多。异步条件问题在真实项目中非常常见。比如审核要调用远程敏感词服务服务返回结果后才会决定是否通过。这套模型的处理方式是把异步调用放在流程引擎之外先把服务结果写入上下文再执行run。条件函数保持纯同步既方便测试也简化引擎实现。驳回后的回退路径是一道典型业务设计题。示例中把rejected的合法去向设为draft和submitted意味着作者可以退回草稿重新修改也可以直接再次提交。很多团队在早期会把rejected直接指向submitted这样省去了一次草稿编辑但作者无法修正内容。具体选择由业务决定类型表只需要如实反映业务规则即可。8. 最佳实践与工程建议8.1 从状态表出发而不是从代码出发在写任何类型之前先画一张状态转移表。表头是当前状态表格内容是合法目标状态单元格里写清楚触发条件。这张表既是业务文档也是TransitionMap的蓝本。示例中的TransitionMap就是状态表直接翻译成代码。8.2 不要让条件函数产生副作用条件函数只做判断不做修改。不要在守卫函数里写日志、发通知、变更上下文。原因有两个一是守卫函数可能被多次调用副作用会被重复执行二是纯函数更容易测试和复用。如果需要记录审计日志放在引擎的run方法或addRule的description中实现。8.3 用穷尽性检查兜住所有 switch所有处理WorkflowStatus的switch都加上default分支并调用assertNever。以后扩展状态编译器会强制找出所有漏改的分支。这是有类型写法最容易忽视、但价值极高的一步。8.4 先替换字符串常量再引入守卫函数如果项目里已经有大量字符串状态代码不要试图一次性重写。第一步把type Status string改成字面量联合类型让编译器把所有不受控的字符串赋值暴露出来。第二步把status draft这类散落判断收敛成一个条件常量或条件函数。第三步再引入TransitionRule。渐进式改造可以显著降低迁移风险。8.5 规则列表保持不可变引擎的rules数组在初始化后不应被外部追加或删除。生产阶段可以把规则注册收敛到一个配置方法里避免运行时被业务代码动态修改。示例中的addRule暴露了修改入口在工程化时可以替换为构造函数注入规则列表。8.6 类型定义和业务文档放一起维护TransitionMap和业务流程图是一体两面。建议在类型文件头部注释里保留一份状态表或者将类型文件放在业务领域目录中而不是放在通用types目录。否则会出现文档和代码分叉业务人员看文档开发人员看类型两边对不上。8.7 善用日志追踪流转路径每条规则都提供description引擎每次跳转都打印来源、去向和原因。这能显著降低生产环境的排查成本拿到一条日志就能知道某个状态为什么发生跳转以及跳到了哪里。真实项目中还可以把流转记录写入数据库或消息队列构建完整审计链。8.8 复杂并发场景考虑成熟状态机库手写引擎适合流程节点有限、并发不高的场景。如果流程中包含并行分支、子流程、超时重试、多实例并发手写实现会明显复杂化。这时候可以考虑引入 XState、Spring StateMachine 等成熟状态机框架本文的类型设计思路仍然适用只是底层的调度能力交给了更成熟的实现。9. 总结与后续学习方向条件工作流的有类型写法核心不是消灭 if-else而是把运行时才暴露的错误提前到编译期。字面量联合类型约束了状态集合映射类型约束了合法跳转泛型守卫函数让条件有了明确签名穷尽性检查让未来扩展不至于漏改分支。这套组合让流程代码在重构时可以放心修改因为编译器会告诉你哪里遗漏了。示例项目虽然只有四个文件但内容审核、订单流转、审批流这些常见场景都能按同一套模式落地。下一步你可以做三件事把手头项目里最频繁出现的字符串状态替换成联合类型为每个状态转移补上守卫条件函数在关键switch分支里加上assertNever兜底。三件事做完流程的可维护性会有明显变化。如果你对状态机本身感兴趣可以继续研究 XState 的建模思想、Java 的 sealed class 模式匹配以及领域驱动设计中对状态流转的建模方式。类型系统只是工具真正重要的是把流程模型变成团队都能理解、编译器都能验证的明确约束。