最近在项目里用 Camunda 重新梳理了一套审批流程从刚开始被概念绕晕到能把 BPMN 流程模型真正跑进 Spring Boot 服务里中间踩了不少坑。Camunda 是目前用得比较多的开源工作流引擎核心就是帮你把流程编排、审批委派、状态流转这些脏活累活接过去让业务代码只关注每个节点上“具体做什么”。这篇文章不写概念 PPT直接按我实际接入并运行一个审批场景的路径来拆解 Camunda包括为什么要选它、核心概念怎么理解、代码怎么写、以及那些文档里不会告诉你的坑适合刚开始接触工作流引擎、或者已经在调研但不知道从哪里下手的 Java 开发者。1. 为什么选 Camunda工作流引擎选型背后的思路1.1 工作流引擎要解决的真实问题很多团队在没接触工作流引擎之前会把审批流程写成一张数据库表加一个状态字段。订单审批、请假审批、报销审批无非就是状态从 0 变到 1再变到 2。刚开始没问题一旦出现会签、或签、超时自动处理、驳回后重新走分支、流程版本变更这几种需求状态机写法会迅速失控因为你要在代码里手动维护“每个状态允许哪些操作”“每个操作把数据流转到哪”。这本质上是把流程逻辑散落在业务代码里而且散落的点往往不只一处业务一多就互相干扰。工作流引擎把一个流程的“流转轨迹”从代码里抽出来变成一份显式的流程定义比如一个 BPMN 文件。Camunda 这类引擎负责解析、执行、暂停、跳转、记录历史业务开发只需要指定“哪个节点做什么事”比如发送一条消息、调用一次外部接口、让某个审批组的人处理待办。这样的好处是流程的改动不再需要重新发版业务代码变的只是节点上的执行器而不是整个状态机。其实这就是 Camunda 名字的由来camunda 在拉丁语里是“门把手”的意思隐喻屏幕上的流程窗口。它在工业界已经用了很多年社区活跃文档齐全代码结构也清晰所以很多中间件、OA、订单系统、制造执行系统里都有它的身影。相比自己写状态机用 Camunda 的代价是一次学习成本但收益是长期可维护的流程资产。1.2 Camunda 与其他方案对比的取舍同类引擎还有 Flowable、Activiti它们都是基于遗留的 jBPM 血统发展出来的。选型的时候主要看几点社区活跃度、引擎嵌入方式、对外开放能力、以及是否需要云原生。Flowable 和 Activiti 在微服务场景下也都能用但 Camunda 在“流程可视化、任务管理、历史数据”上的默认体验更完整自带 Cockpit 控制台能直接看流程实例跑到了哪个节点。我自己更看重的是 Camunda 的“流程引擎即服务”的边界感。它不强迫业务代码改自己的领域模型而是通过外部变量和委托代码接入耦合度低。反观某些引擎会鼓励你把业务放到它的实体类上后期升级非常痛苦。在对比中可以看下表对比项Camunda 7Camunda 8Flowable部署方式嵌入式/独立服务云原生 Zeebe 集群嵌入式/独立服务核心 APIJava API RESTZeebe 客户端 gRPCJava API REST建模语言BPMN、DMN、CMMNBPMN DMNBPMN、DMN、CMMN单机友好度高直接跑 Spring Boot中需要 Broker 集群高轻量集成生产运维要求中数据库依赖高需要容器编排中如果你的团队已经使用了 Spring Boot而且不想为了流程引擎引入整套分布式基础设施Camunda 7 是最务实的起点。它的进程内引擎模式意味着业务应用直接拿到 Java API流程操作和业务操作在一个本地事务里一致性处理起来最简单。Camunda 8 更适合流量大、需要弹性伸缩的独立流程服务但引入成本也更高。1.3 版本选择先搞定 7 还是直接上 8Camunda 7 和 8 的差异不只是版本号问题而是两套完全不同的架构。7 是经典的命令式引擎流程实例的执行由引擎内部的命令栈驱动一个流程实例就是一个数据库状态机适合传统单体或多模块应用。8 基于 Zeebe 构建是分布式流处理架构流程以事件流的方式在分区中存储客户端通过 gRPC 提交命令由 Broker 集群处理适合独立部署的微服务流程平台。对于第一次上手、想在项目里快速看到效果的人建议直接学 Camunda 7。它部署简单一个 Spring Boot 工程加上依赖就能跑社区里遇到的绝大多数问题都能搜到答案。Camunda 8 的思维模型更复杂涉及分区、流、长期运行工作流、导出器等概念如果一上来就学习 8容易被基础设施分心反而忽略了 BPMN 建模这个核心。但如果你已经确认要做“独立流程中台”且能接受用 Docker Compose 或 Kubernetes 维护一套集群那么 8 的吞吐量和隔离性更好。本文后面的实操代码基于 Camunda 7.20 版本这也是当前最主流的稳定线所有示例在生产环境可直接落地。2. 核心概念与建模语言BPMN 不只是画流程图2.1 BPMN 模型的关键元素与一个审批例子很多人第一次使用 Camunda 时会觉得 BPMN 建模就像用 Visio 画流程图拖几个方块连几条线。这种理解会导致后续流程跑起来动不动就卡住因为忽略了一个重点BPMN 是“可执行”的流程语言每个元素都有约定俗成的执行语义。最常用的元素有三类事件、网关、任务。事件用圆圈表示开始事件是流程的入口结束事件是流程出口中间常配合定时器做超时处理。网关用菱形表示排他网关只能走一个分支并行网关会把流程令牌复制成多份让多分支同时推进。任务用圆角矩形表示用户任务专门给人工处理待办服务任务交给程序自动执行。除了这些还要理解边界事件它挂在某个任务外面用于处理这个任务执行期间出现的异常或者超时这是很多场景都依赖的机制。举个实际审批例子员工提交报销单金额小于 500 走直属主管审批大于等于 500 需要部门经理和财务会签审批通过后打款接口自动执行打款失败会走到异常处理人工介入。这个流程用 BPMN 表达时会包含两个排他网关、一个并行网关、两个服务任务、若干用户任务。每一个连线条件比如金额大于等于 500需要表达式写在连线的 conditionExpression 里表达式引擎用本地变量计算。流程跑起来后引擎会生成一个流程实例实例内有独立的变量作用域引擎通过令牌移动决定下一步激活哪个节点。BPMN 建模的核心不是画图美观而是明确“谁先谁后、谁能并行、什么条件下改道、超时怎么办”。在 Camunda Modeler 里画图时应该先写清楚每个分支的条件表达式再设置用户任务的候选组最后才是布局调整。否则流程模型建议器不会报错但放到引擎里执行时就会出现条件表达式中引用不存在的变量导致流程实例停在中间。2.2 DMN 与 CMMN 的适用范围区分BPMN 解决的是“按固定顺序执行”的过程编排问题但现实中的业务还有两类问题它不方便处理一类是规则太多且经常变比如审批额度、风险等级、折扣率另一类是“无固定流程”的案例情况比如售后工单可能要调查、维修、回访顺序不固定但最终要闭环。针对规则问题Camunda 用 DMN决策模型来管理。DMN 本质是一张决策表每一行是规则每一列是条件或结论。举个例子信用额度审批中根据客户的信用评级和申请金额决定“自动通过”“人工复核”“拒绝”这个逻辑写在 DMN 表里通过决策引擎调用业务代码不参与判断即使修改规则也只要重新发布 DMN 模型不用改 Java。针对案例型流程使用 CMMN它用计划项目表表达“可能需要执行的活动”而不是强制顺序适合工单、投诉事件、检查任务这类动态场景。在落地时要注意很多项目连 BPMN 都没用熟练就想着上 CMMN结果把流程搞得特别“自由”反而没法跟踪。我的建议是先用 BPMN 固定主线流程将分支条件优先抽取成 DMN 决策表只有遇到真正的非结构化协同时才启用 CMMN。这样既减少了流程模型数量又让规则与流程分离。2.3 流程实例、执行与变量的理解流程定义相当于类流程实例相当于对象。这句话是按类比的常规理解但要清楚它的内部语义。一个流程实例从开始事件启动生成一个根执行Execution根执行是流程实例内部的主令牌。遇到并行网关时会产生多个子执行每个分支上都有独立的令牌用于记录当前走到哪个节点。变量是流程实例的生命线。在 Camunda 里变量按作用域可以分为流程实例级和局部级。流程实例级变量全局可见比如申请金额、申请人局部级变量只存在于某个执行范围比如并行分支中某个服务任务内部的临时结果。定义变量的方式很多启动流程实例时传入、任务完成时设置、服务任务内通过 delegateExecution 的 setVariable 方法设置。开发时需要特别注意变量类型Camunda 默认用 JSON 序列化存储复杂对象建议只存能 JSON 化的简单类型避免存储 Java 对象与序列化版本不一致导致的反序列化问题。流程定义发布后是不可变的。当新流程部署时引擎生成新的版本号新的流程实例默认使用最新版本但可以通过流程实例的 processDefinitionId 指定使用旧的版本。这个机制保证了“线上还在跑的单子不会因为模型改动被打断”。这也是工作流引擎最有价值的特性之一。3. 从零落地一个审批流程实操步骤与代码3.1 环境准备与依赖引入这里使用 Spring Boot 3.2 与 Camunda 7.20 组合来说明。简要起见直接引入如下 Maven 依赖dependency groupIdorg.camunda.bpm.springboot/groupId artifactIdcamunda-bpm-spring-boot-starter/artifactId version7.20.0/version /dependency dependency groupIdorg.camunda.bpm.springboot/groupId artifactIdcamunda-bpm-spring-boot-starter-rest/artifactId version7.20.0/version /dependency dependency groupIdorg.camunda.bpm.springboot/groupId artifactIdcamunda-bpm-spring-boot-starter-webapp/artifactId version7.20.0/version /dependencycamunda-bpm-spring-boot-starter 是核心引擎starter-rest 用于暴露 REST APIstarter-webapp 则会内置 Cockpit/Admin/Tasklist 三个 Web 应用方便开发和调试。生产环境建议去掉 webapp只保留核心引擎和 REST 接口否则会多出很多运维面。数据库配置也值得一提。Camunda 7 需要使用关系型数据库保存三部分数据流程定义的部署数据、运行时数据正在运行的流程实例、任务、变量、历史数据。官方支持 MySQL、PostgreSQL、Oracle、SQL Server 等配置方式就是普通的 DataSource。我用 PostgreSQL 比较多引擎会自动创建 ACT_RE_、ACT_RU_、ACT_HI_、ACT_ID_、ACT_DMN_ 这些前缀的表不需要手动建表。一个常见的坑是数据库账号权限不足导致启动时建表语句执行失败所以在第一次启动前确认账号有 DDL 权限否则引擎启动直接报错。配置文件里历史登记级别建议默认设为 auditcamunda.bpm: history-level: audit admin-user: id: admin password: admin firstName: Admin authorization-enabled: truehistory-level 控制历史数据的详细程度。none 只保存运行数据不清历史activity 保存流程实例和活动实例数据audit 增加变量更新、表单属性等full 保存所有事件。为了排障方便我一般用 audit它已经能覆盖绝大多数查询不会像 full 那样产生大量事件记录导致历史表膨胀。3.2 设计一个审批流程模型直接用 Camunda Modeler 新建 BPMN 图这里给一个关键的流程设计思路不贴完整 XML因为 Modeler 生成的 XML 很长。模型命名为 expense-approval包含以下节点顺序开始事件 - 填写报销单用户任务 - 提交申请服务任务自动给主管生成审批任务 - 排他网关判断金额 - 主管审批金额小于 500或 部门经理审批金额不小于 500 - 排他网关判断审批是否为通过 - 通过则进入财务打款服务任务 - 打款失败抛异常 - 边界异常事件跳转到人工处理用户任务 - 结束事件审批驳回则直接到驳回结束事件。模型中的两个关键点一是主管审批任务使用候选组 managerGroup二是金额判断条件写在排他网关上表达式为 ${amount 500} 和 ${amount 500}。用户任务配置中assignee 或 candidateUsers、candidateGroups 都可以指定处理人。最灵活的方式是通过 camunda 表单或者流程变量动态指定比如在开始节点前通过业务数据设置 nextApprover 变量然后在用户任务的 assignee 中填 ${nextApprover}。模型设计上最容易踩的坑是网关连接线条件的“非穷尽”。如果有多个流出连线排他网关根据条件表达式求值多个为 true 时取第一个求值为 true 的没有为 true 时引擎会抛出异常并终止流程实例。所以设计时必须保证有一个默认分支在 Modeler 里把兜底分支的默认流标识出来。3.3 部署流程与启动流程实例流程模型做好后如何在服务里部署最常见的方式是在启动时自动部署 classpath 下的 bpmn 文件。Spring Boot Starter 默认会扫描并自动部署 resources 目录下的 bpmn 文件不需要手动代码。如果希望更精确地控制部署或者用代码方式部署可以通过 RepositoryService 实现Autowired private RepositoryService repositoryService; public void deployProcess() { DeploymentBuilder builder repositoryService.createDeployment() .name(expense-approval) .addClasspathResource(processes/expense-approval.bpmn) .source(expense-approval); Deployment deployment builder.deploy(); System.out.println(部署ID: deployment.getId()); }部署后每个流程定义会生成一个新的部署版本。如果你重复部署同一个流程文件Camunda 7 会基于资源的哈希值做重复检测如果内容一致即使部署多次也只会保存一份新版本。内容有改动才会重新解析生成新版本。启动流程实例也很简单Autowired private RuntimeService runtimeService; public void startApprovalProcess(String businessKey, long amount) { MapString, Object variables new HashMap(); variables.put(amount, amount); variables.put(applicant, 张三); variables.put(status, INIT); ProcessInstance instance runtimeService.startProcessInstanceByKey( expense-approval, businessKey, variables); }startProcessInstanceByKey 的含义是使用流程定义 key 启动最新版本的流程。流程定义 key 在 Modeler 的属性面板里设置比如设为 expense-approval。businessKey 是业务与流程的关联键比如报销单号之后可以通过业务键反查流程实例这个字段在生产环境中应该充分利用避免把整个业务对象塞进变量。3.4 处理用户任务与实现服务任务启动流程后流程会停在“填写报销单”用户任务上。业务系统的待办列表可以通过 TaskService 查询ListTask tasks taskService.createTaskQuery() .processDefinitionKey(expense-approval) .taskAssignee(张三) .list();完成任务时需要传入结果变量MapString, Object vars new HashMap(); vars.put(isApproved, true); taskService.complete(taskId, vars);任务完成是个分水岭。引擎会在同一个事务内执行当前任务完成动作接着评估出口连线表达式向后推进。如果后面的服务任务抛出异常整个事务会回滚任务会再次回到未完成状态这就是流程引擎事务边界的表现。利用这一点可以保证“任务完成 后续服务执行”的原子性。如果一个服务任务调用的外部系统在流程中途失败可能还在同一个事务里或者如果服务任务被边界事件捕获则进入补偿分支。服务任务的实现方式有两种第一种是使用 JavaDelegate 委托类类实现某个接口在 execute 方法里写业务逻辑第二种是使用表达式调用 Spring Bean 方法。推荐后者因为可以直接注入 Service。Component(paymentService) public class PaymentService { public void executePayment(DelegateExecution execution) { Object amount execution.getVariable(amount); // 调用支付接口 boolean success invokePayment(order- execution.getBusinessKey(), amount); if (!success) { throw new BpmnError(PAY_ERROR, 支付失败); } } }在 BPMN 模型的服务任务中设置 Java/表达式为 ${paymentService.executePayment}引擎就会在每次进入该节点时调用对应方法。这里要特别说明执行器内可以处理业务逻辑、读写流程变量但不要使用 Camunda 的 RuntimeService 去主动启动或推进同一个流程实例这样容易导致递归命令提高复杂度。对流程实例的修改应该通过当前执行的上下文完成。在实际项目中服务任务最常犯的错误是把长时间的网络调用直接放在委托方法内导致事务长期挂起、数据库连接被占满。解决思路是把耗时的外部调用拆成两步第一步快速落库保存“待发送”状态第二步通过异步任务执行真正的网络调用再回调更新结果。Camunda 7 也提供了异步延续机制在服务任务属性中勾选 async before / async after让引擎把任务放入 Job 队列通过 Job Executor 异步执行。如果外部接口响应时间通常超过 2 秒建议一定开启异步否则用户任务完成时感受不到“提交”因为请求在服务任务上卡住了。3.5 流程测试与单元测试Camunda 的流程不能只靠手工点按钮验证必须写自动化测试。Camunda 官方提供了 camunda-bpm-assert 断言库配合 JUnit 使用能减少很多验证代码。dependency groupIdorg.camunda.bpm.extension/groupId artifactIdcamunda-bpm-assert/artifactId version2.0.2/version scopetest/scope /dependency测试类的基本模板SpringBootTest Deployment(resources {processes/expense-approval.bpmn}) public class ExpenseApprovalProcessTest { Autowired private RuntimeService runtimeService; Test public void shouldApproveWhenAmountLessThan500() { MapString, Object vars new HashMap(); vars.put(amount, 300); ProcessInstance instance runtimeService.startProcessInstanceByKey(expense-approval, vars); assertThat(instance) .isStarted() .task() .hasName(填写报销单); // 完成填写报销单 TaskService taskService null; // 自动注入 // 实际中通过 taskQuery 获取任务完成它再继续断言后续任务 } }Deployment 注解会在测试用例前单独部署流程测试结束后自动清理避免多个测试之间版本冲突。流程测试的核心目标是验证“每个网关条件是否按预期流转”而业务逻辑应该在委托类本身的单元测试中写清楚。测试时还需要设置全局时间为确定性时间避免定时边界事件干扰断言。Camunda 提供 ClockUtil 的静态方法// 设置引擎内部时钟 ProcessEngine processEngine ProcessEngines.getDefaultProcessEngine(); processEngine.getProcessEngineConfiguration().getClock().setCurrentTime(new Date(2025/01/01 00:00:00));我自己的习惯是每个流程至少写通过、驳回、异常边界、超时四条路径这四条覆盖了大多数生产问题。4. 常见问题与排查技巧实录4.1 部署新版本后旧实例跑不动有朋友遇到这样的问题线上跑了很久的流程实例更新模型后所有新任务都不见了甚至流程实例挂起。排查后发现是因为部署新版本时改了流程 key或者把节点 key 给改了。Camunda 按节点 key 关联历史活动和任务所以一旦改动节点 id旧实例后续的节点映射就会失效。经验教训流程模型上线后节点 key 绝不能改。如果要改名字只改 name 属性不要改 id。如果一定要删除中间节点建议先评估在途实例或者通过流程迁移 API 将旧实例迁移到新定义前提是节点映射关系能在模型匹配上。流程定义版本的平滑切换是引擎最强大的能力也最容易因为不守规矩而引发故障。4.2 事务回滚与边界事件冲突服务任务中抛出 BpmnError 会被边界事件捕获这是一种业务异常处理路径。如果是抛出其他 Runtime 异常则引擎事务直接回滚流程实例状态回到进入服务任务前的状态。这里有个常见误解以为边界事件能捕获所有异常。实际上只有 BpmnError 会被捕获普通异常不会进入边界事件。所以在代码里务必明确区分业务失败和系统错误。针对支付失败这类业务异常使用 BpmnError针对返回 500 这种系统异常应当让事务回滚或者用异步 Job 重试机制。另外如果委托方法内捕获了异常并吞掉什么都不做那么服务任务就会被认为执行成功继续向下走这是最隐蔽的错误路径。生产日志里出现“流程实例莫名其妙就走完了”的情况多数是空 catch 导致的。4.3 历史表增长与性能优化Camunda 7 的历史表会随着流程实例数量线性增长尤其是 ACT_HI_VARINST变量历史表写得很频繁。如果系统每天跑上万个流程实例一个月后历史表可能达到几千万行查询会明显变慢。解决思路有三个方向。一是按时间定期清理历史数据Camunda 提供了历史清理机制通过配置历史清理策略可以只保留最近 90 天的历史数据。二是在部署流程时进行流程实例统计热点流程可以设置 historical activity 为不记录但尽量少做因为会丢掉排障数据。三是为常用查询添加索引特别是按 business_key、按 process_definition_key 的过滤条件。更彻底的架构手段是把历史数据做数据归档定期把 ACT_HI_ 表的数据转储到归档库并删除源库这样引擎库始终维持可控体积查询也不会被归档拖累。4.4 并发场景与集群部署的坑Camunda 7 默认以数据库行锁保证并发一致性。两个用户同时完成同一个任务时一个成功另一个会抛 PessimisticLockingFailureException原因是数据库行锁等待超时。表面上看起来像是偶发报错但其实是正常的并发保护。此时业务系统应该捕获该异常并提示用户“任务已被处理”而不是盲目重试。集群部署时Camunda 7 支持多节点共享数据库通过 Quartz Job Executor 抢占式执行异步任务。默认的 Job Executor 每个节点都会去抢但同一个 Job 在同一时间只能被一个节点执行数据库锁保证这一点。配置时要注意节点间系统时钟尽量一致否则定时任务的准时性会受到印象。Camunda 8Zeebe则没有这个问题它通过分区与 Leader 机制天然协调多节点执行。从运维角度说集群部署 Camunda 7 的核心是数据库的高可用不要为了追求引擎高可用而部署多个节点却忽略了数据库的单点风险。数据库挂了集群节点再多也白搭。5. 真实案例复盘一个审批流程的落地过程最后分享一个我在制造业项目里实际落地 Camunda 的简化版本供参考。业务场景是设备点检流程。设备每月需要点检由点检员填写点检单包含设备编号、点检项目、是否异常。如果设备异常需要创建维修工单由维修组长派工给维修工维修完成后验证人验证通过才闭环。异常信息还要同步到质量部门。我们使用 Camunda 7 部署了两个主要流程。第一个是“点检异常触发流程”由点检单创建事件触发流程如下开始事件消息事件 - 写入工单表服务任务 - 维修组长审批用户任务 - 并行分支一个分支推送通知给质量部另一个分支等待维修完成。在这套流程中我们用 DMN 决策表处理“什么样的异常需要立即停机”的规则。当异常设备涉及关键生产设备且异常级别为“严重”时决策表返回 true流程会启动一条紧急停机审批子流程否则只进入普通维修。这个设计很清楚地展示了 BPMN 处理流程编排、DMN 处理规则判断的好处业务代码里不再有复杂的 if 嵌套。实施中的关键时间点第一天引入依赖写好流程模型骨架第二天实现两个服务任务和用户任务的查询接口第三天完成联调包括边界事件、异常捕获。整体比用状态机写效率高很多因为和业务方讨论时是直接看流程图而不是翻代码。6. 写在最后的经验提醒我一直觉得工作流引擎的引入不是技术问题而是建模意识问题。Camunda 把流程可视化、自动化、版本化做得足够好但它不会替你想清楚每一步谁负责、条件怎么判、失败怎么降级。建模前花时间梳理业务规则比用任何高深 API 都重要。我在第一次用 Camunda 时以为把流程画出来就能跑后来发现流程图上多数节点只是表达“有人看一眼”而没有任何实际动作这种模型对业务没有正向价值。如果让我给一条最核心的建议从最小的端到端流程开始跑通后再逐步增加网关、边界事件、DMN 决策。不要一开始就在流程里塞并行网关和子流程否则你连最基础的贯穿链路都没验证就被并行分支和事务边界问题淹没了。踩过几次坑之后我现在更倾向于把“异常处理路径”放在最前面设计也就是先想清楚哪些环节会失败、失败之后往哪里走而不是先画主路径。主路径人人都能画真正体现工程能力的恰恰是那些不在主路径上的分支与补偿逻辑。
Camunda工作流引擎实战：审批流程从建模到Spring Boot落地
最近在项目里用 Camunda 重新梳理了一套审批流程从刚开始被概念绕晕到能把 BPMN 流程模型真正跑进 Spring Boot 服务里中间踩了不少坑。Camunda 是目前用得比较多的开源工作流引擎核心就是帮你把流程编排、审批委派、状态流转这些脏活累活接过去让业务代码只关注每个节点上“具体做什么”。这篇文章不写概念 PPT直接按我实际接入并运行一个审批场景的路径来拆解 Camunda包括为什么要选它、核心概念怎么理解、代码怎么写、以及那些文档里不会告诉你的坑适合刚开始接触工作流引擎、或者已经在调研但不知道从哪里下手的 Java 开发者。1. 为什么选 Camunda工作流引擎选型背后的思路1.1 工作流引擎要解决的真实问题很多团队在没接触工作流引擎之前会把审批流程写成一张数据库表加一个状态字段。订单审批、请假审批、报销审批无非就是状态从 0 变到 1再变到 2。刚开始没问题一旦出现会签、或签、超时自动处理、驳回后重新走分支、流程版本变更这几种需求状态机写法会迅速失控因为你要在代码里手动维护“每个状态允许哪些操作”“每个操作把数据流转到哪”。这本质上是把流程逻辑散落在业务代码里而且散落的点往往不只一处业务一多就互相干扰。工作流引擎把一个流程的“流转轨迹”从代码里抽出来变成一份显式的流程定义比如一个 BPMN 文件。Camunda 这类引擎负责解析、执行、暂停、跳转、记录历史业务开发只需要指定“哪个节点做什么事”比如发送一条消息、调用一次外部接口、让某个审批组的人处理待办。这样的好处是流程的改动不再需要重新发版业务代码变的只是节点上的执行器而不是整个状态机。其实这就是 Camunda 名字的由来camunda 在拉丁语里是“门把手”的意思隐喻屏幕上的流程窗口。它在工业界已经用了很多年社区活跃文档齐全代码结构也清晰所以很多中间件、OA、订单系统、制造执行系统里都有它的身影。相比自己写状态机用 Camunda 的代价是一次学习成本但收益是长期可维护的流程资产。1.2 Camunda 与其他方案对比的取舍同类引擎还有 Flowable、Activiti它们都是基于遗留的 jBPM 血统发展出来的。选型的时候主要看几点社区活跃度、引擎嵌入方式、对外开放能力、以及是否需要云原生。Flowable 和 Activiti 在微服务场景下也都能用但 Camunda 在“流程可视化、任务管理、历史数据”上的默认体验更完整自带 Cockpit 控制台能直接看流程实例跑到了哪个节点。我自己更看重的是 Camunda 的“流程引擎即服务”的边界感。它不强迫业务代码改自己的领域模型而是通过外部变量和委托代码接入耦合度低。反观某些引擎会鼓励你把业务放到它的实体类上后期升级非常痛苦。在对比中可以看下表对比项Camunda 7Camunda 8Flowable部署方式嵌入式/独立服务云原生 Zeebe 集群嵌入式/独立服务核心 APIJava API RESTZeebe 客户端 gRPCJava API REST建模语言BPMN、DMN、CMMNBPMN DMNBPMN、DMN、CMMN单机友好度高直接跑 Spring Boot中需要 Broker 集群高轻量集成生产运维要求中数据库依赖高需要容器编排中如果你的团队已经使用了 Spring Boot而且不想为了流程引擎引入整套分布式基础设施Camunda 7 是最务实的起点。它的进程内引擎模式意味着业务应用直接拿到 Java API流程操作和业务操作在一个本地事务里一致性处理起来最简单。Camunda 8 更适合流量大、需要弹性伸缩的独立流程服务但引入成本也更高。1.3 版本选择先搞定 7 还是直接上 8Camunda 7 和 8 的差异不只是版本号问题而是两套完全不同的架构。7 是经典的命令式引擎流程实例的执行由引擎内部的命令栈驱动一个流程实例就是一个数据库状态机适合传统单体或多模块应用。8 基于 Zeebe 构建是分布式流处理架构流程以事件流的方式在分区中存储客户端通过 gRPC 提交命令由 Broker 集群处理适合独立部署的微服务流程平台。对于第一次上手、想在项目里快速看到效果的人建议直接学 Camunda 7。它部署简单一个 Spring Boot 工程加上依赖就能跑社区里遇到的绝大多数问题都能搜到答案。Camunda 8 的思维模型更复杂涉及分区、流、长期运行工作流、导出器等概念如果一上来就学习 8容易被基础设施分心反而忽略了 BPMN 建模这个核心。但如果你已经确认要做“独立流程中台”且能接受用 Docker Compose 或 Kubernetes 维护一套集群那么 8 的吞吐量和隔离性更好。本文后面的实操代码基于 Camunda 7.20 版本这也是当前最主流的稳定线所有示例在生产环境可直接落地。2. 核心概念与建模语言BPMN 不只是画流程图2.1 BPMN 模型的关键元素与一个审批例子很多人第一次使用 Camunda 时会觉得 BPMN 建模就像用 Visio 画流程图拖几个方块连几条线。这种理解会导致后续流程跑起来动不动就卡住因为忽略了一个重点BPMN 是“可执行”的流程语言每个元素都有约定俗成的执行语义。最常用的元素有三类事件、网关、任务。事件用圆圈表示开始事件是流程的入口结束事件是流程出口中间常配合定时器做超时处理。网关用菱形表示排他网关只能走一个分支并行网关会把流程令牌复制成多份让多分支同时推进。任务用圆角矩形表示用户任务专门给人工处理待办服务任务交给程序自动执行。除了这些还要理解边界事件它挂在某个任务外面用于处理这个任务执行期间出现的异常或者超时这是很多场景都依赖的机制。举个实际审批例子员工提交报销单金额小于 500 走直属主管审批大于等于 500 需要部门经理和财务会签审批通过后打款接口自动执行打款失败会走到异常处理人工介入。这个流程用 BPMN 表达时会包含两个排他网关、一个并行网关、两个服务任务、若干用户任务。每一个连线条件比如金额大于等于 500需要表达式写在连线的 conditionExpression 里表达式引擎用本地变量计算。流程跑起来后引擎会生成一个流程实例实例内有独立的变量作用域引擎通过令牌移动决定下一步激活哪个节点。BPMN 建模的核心不是画图美观而是明确“谁先谁后、谁能并行、什么条件下改道、超时怎么办”。在 Camunda Modeler 里画图时应该先写清楚每个分支的条件表达式再设置用户任务的候选组最后才是布局调整。否则流程模型建议器不会报错但放到引擎里执行时就会出现条件表达式中引用不存在的变量导致流程实例停在中间。2.2 DMN 与 CMMN 的适用范围区分BPMN 解决的是“按固定顺序执行”的过程编排问题但现实中的业务还有两类问题它不方便处理一类是规则太多且经常变比如审批额度、风险等级、折扣率另一类是“无固定流程”的案例情况比如售后工单可能要调查、维修、回访顺序不固定但最终要闭环。针对规则问题Camunda 用 DMN决策模型来管理。DMN 本质是一张决策表每一行是规则每一列是条件或结论。举个例子信用额度审批中根据客户的信用评级和申请金额决定“自动通过”“人工复核”“拒绝”这个逻辑写在 DMN 表里通过决策引擎调用业务代码不参与判断即使修改规则也只要重新发布 DMN 模型不用改 Java。针对案例型流程使用 CMMN它用计划项目表表达“可能需要执行的活动”而不是强制顺序适合工单、投诉事件、检查任务这类动态场景。在落地时要注意很多项目连 BPMN 都没用熟练就想着上 CMMN结果把流程搞得特别“自由”反而没法跟踪。我的建议是先用 BPMN 固定主线流程将分支条件优先抽取成 DMN 决策表只有遇到真正的非结构化协同时才启用 CMMN。这样既减少了流程模型数量又让规则与流程分离。2.3 流程实例、执行与变量的理解流程定义相当于类流程实例相当于对象。这句话是按类比的常规理解但要清楚它的内部语义。一个流程实例从开始事件启动生成一个根执行Execution根执行是流程实例内部的主令牌。遇到并行网关时会产生多个子执行每个分支上都有独立的令牌用于记录当前走到哪个节点。变量是流程实例的生命线。在 Camunda 里变量按作用域可以分为流程实例级和局部级。流程实例级变量全局可见比如申请金额、申请人局部级变量只存在于某个执行范围比如并行分支中某个服务任务内部的临时结果。定义变量的方式很多启动流程实例时传入、任务完成时设置、服务任务内通过 delegateExecution 的 setVariable 方法设置。开发时需要特别注意变量类型Camunda 默认用 JSON 序列化存储复杂对象建议只存能 JSON 化的简单类型避免存储 Java 对象与序列化版本不一致导致的反序列化问题。流程定义发布后是不可变的。当新流程部署时引擎生成新的版本号新的流程实例默认使用最新版本但可以通过流程实例的 processDefinitionId 指定使用旧的版本。这个机制保证了“线上还在跑的单子不会因为模型改动被打断”。这也是工作流引擎最有价值的特性之一。3. 从零落地一个审批流程实操步骤与代码3.1 环境准备与依赖引入这里使用 Spring Boot 3.2 与 Camunda 7.20 组合来说明。简要起见直接引入如下 Maven 依赖dependency groupIdorg.camunda.bpm.springboot/groupId artifactIdcamunda-bpm-spring-boot-starter/artifactId version7.20.0/version /dependency dependency groupIdorg.camunda.bpm.springboot/groupId artifactIdcamunda-bpm-spring-boot-starter-rest/artifactId version7.20.0/version /dependency dependency groupIdorg.camunda.bpm.springboot/groupId artifactIdcamunda-bpm-spring-boot-starter-webapp/artifactId version7.20.0/version /dependencycamunda-bpm-spring-boot-starter 是核心引擎starter-rest 用于暴露 REST APIstarter-webapp 则会内置 Cockpit/Admin/Tasklist 三个 Web 应用方便开发和调试。生产环境建议去掉 webapp只保留核心引擎和 REST 接口否则会多出很多运维面。数据库配置也值得一提。Camunda 7 需要使用关系型数据库保存三部分数据流程定义的部署数据、运行时数据正在运行的流程实例、任务、变量、历史数据。官方支持 MySQL、PostgreSQL、Oracle、SQL Server 等配置方式就是普通的 DataSource。我用 PostgreSQL 比较多引擎会自动创建 ACT_RE_、ACT_RU_、ACT_HI_、ACT_ID_、ACT_DMN_ 这些前缀的表不需要手动建表。一个常见的坑是数据库账号权限不足导致启动时建表语句执行失败所以在第一次启动前确认账号有 DDL 权限否则引擎启动直接报错。配置文件里历史登记级别建议默认设为 auditcamunda.bpm: history-level: audit admin-user: id: admin password: admin firstName: Admin authorization-enabled: truehistory-level 控制历史数据的详细程度。none 只保存运行数据不清历史activity 保存流程实例和活动实例数据audit 增加变量更新、表单属性等full 保存所有事件。为了排障方便我一般用 audit它已经能覆盖绝大多数查询不会像 full 那样产生大量事件记录导致历史表膨胀。3.2 设计一个审批流程模型直接用 Camunda Modeler 新建 BPMN 图这里给一个关键的流程设计思路不贴完整 XML因为 Modeler 生成的 XML 很长。模型命名为 expense-approval包含以下节点顺序开始事件 - 填写报销单用户任务 - 提交申请服务任务自动给主管生成审批任务 - 排他网关判断金额 - 主管审批金额小于 500或 部门经理审批金额不小于 500 - 排他网关判断审批是否为通过 - 通过则进入财务打款服务任务 - 打款失败抛异常 - 边界异常事件跳转到人工处理用户任务 - 结束事件审批驳回则直接到驳回结束事件。模型中的两个关键点一是主管审批任务使用候选组 managerGroup二是金额判断条件写在排他网关上表达式为 ${amount 500} 和 ${amount 500}。用户任务配置中assignee 或 candidateUsers、candidateGroups 都可以指定处理人。最灵活的方式是通过 camunda 表单或者流程变量动态指定比如在开始节点前通过业务数据设置 nextApprover 变量然后在用户任务的 assignee 中填 ${nextApprover}。模型设计上最容易踩的坑是网关连接线条件的“非穷尽”。如果有多个流出连线排他网关根据条件表达式求值多个为 true 时取第一个求值为 true 的没有为 true 时引擎会抛出异常并终止流程实例。所以设计时必须保证有一个默认分支在 Modeler 里把兜底分支的默认流标识出来。3.3 部署流程与启动流程实例流程模型做好后如何在服务里部署最常见的方式是在启动时自动部署 classpath 下的 bpmn 文件。Spring Boot Starter 默认会扫描并自动部署 resources 目录下的 bpmn 文件不需要手动代码。如果希望更精确地控制部署或者用代码方式部署可以通过 RepositoryService 实现Autowired private RepositoryService repositoryService; public void deployProcess() { DeploymentBuilder builder repositoryService.createDeployment() .name(expense-approval) .addClasspathResource(processes/expense-approval.bpmn) .source(expense-approval); Deployment deployment builder.deploy(); System.out.println(部署ID: deployment.getId()); }部署后每个流程定义会生成一个新的部署版本。如果你重复部署同一个流程文件Camunda 7 会基于资源的哈希值做重复检测如果内容一致即使部署多次也只会保存一份新版本。内容有改动才会重新解析生成新版本。启动流程实例也很简单Autowired private RuntimeService runtimeService; public void startApprovalProcess(String businessKey, long amount) { MapString, Object variables new HashMap(); variables.put(amount, amount); variables.put(applicant, 张三); variables.put(status, INIT); ProcessInstance instance runtimeService.startProcessInstanceByKey( expense-approval, businessKey, variables); }startProcessInstanceByKey 的含义是使用流程定义 key 启动最新版本的流程。流程定义 key 在 Modeler 的属性面板里设置比如设为 expense-approval。businessKey 是业务与流程的关联键比如报销单号之后可以通过业务键反查流程实例这个字段在生产环境中应该充分利用避免把整个业务对象塞进变量。3.4 处理用户任务与实现服务任务启动流程后流程会停在“填写报销单”用户任务上。业务系统的待办列表可以通过 TaskService 查询ListTask tasks taskService.createTaskQuery() .processDefinitionKey(expense-approval) .taskAssignee(张三) .list();完成任务时需要传入结果变量MapString, Object vars new HashMap(); vars.put(isApproved, true); taskService.complete(taskId, vars);任务完成是个分水岭。引擎会在同一个事务内执行当前任务完成动作接着评估出口连线表达式向后推进。如果后面的服务任务抛出异常整个事务会回滚任务会再次回到未完成状态这就是流程引擎事务边界的表现。利用这一点可以保证“任务完成 后续服务执行”的原子性。如果一个服务任务调用的外部系统在流程中途失败可能还在同一个事务里或者如果服务任务被边界事件捕获则进入补偿分支。服务任务的实现方式有两种第一种是使用 JavaDelegate 委托类类实现某个接口在 execute 方法里写业务逻辑第二种是使用表达式调用 Spring Bean 方法。推荐后者因为可以直接注入 Service。Component(paymentService) public class PaymentService { public void executePayment(DelegateExecution execution) { Object amount execution.getVariable(amount); // 调用支付接口 boolean success invokePayment(order- execution.getBusinessKey(), amount); if (!success) { throw new BpmnError(PAY_ERROR, 支付失败); } } }在 BPMN 模型的服务任务中设置 Java/表达式为 ${paymentService.executePayment}引擎就会在每次进入该节点时调用对应方法。这里要特别说明执行器内可以处理业务逻辑、读写流程变量但不要使用 Camunda 的 RuntimeService 去主动启动或推进同一个流程实例这样容易导致递归命令提高复杂度。对流程实例的修改应该通过当前执行的上下文完成。在实际项目中服务任务最常犯的错误是把长时间的网络调用直接放在委托方法内导致事务长期挂起、数据库连接被占满。解决思路是把耗时的外部调用拆成两步第一步快速落库保存“待发送”状态第二步通过异步任务执行真正的网络调用再回调更新结果。Camunda 7 也提供了异步延续机制在服务任务属性中勾选 async before / async after让引擎把任务放入 Job 队列通过 Job Executor 异步执行。如果外部接口响应时间通常超过 2 秒建议一定开启异步否则用户任务完成时感受不到“提交”因为请求在服务任务上卡住了。3.5 流程测试与单元测试Camunda 的流程不能只靠手工点按钮验证必须写自动化测试。Camunda 官方提供了 camunda-bpm-assert 断言库配合 JUnit 使用能减少很多验证代码。dependency groupIdorg.camunda.bpm.extension/groupId artifactIdcamunda-bpm-assert/artifactId version2.0.2/version scopetest/scope /dependency测试类的基本模板SpringBootTest Deployment(resources {processes/expense-approval.bpmn}) public class ExpenseApprovalProcessTest { Autowired private RuntimeService runtimeService; Test public void shouldApproveWhenAmountLessThan500() { MapString, Object vars new HashMap(); vars.put(amount, 300); ProcessInstance instance runtimeService.startProcessInstanceByKey(expense-approval, vars); assertThat(instance) .isStarted() .task() .hasName(填写报销单); // 完成填写报销单 TaskService taskService null; // 自动注入 // 实际中通过 taskQuery 获取任务完成它再继续断言后续任务 } }Deployment 注解会在测试用例前单独部署流程测试结束后自动清理避免多个测试之间版本冲突。流程测试的核心目标是验证“每个网关条件是否按预期流转”而业务逻辑应该在委托类本身的单元测试中写清楚。测试时还需要设置全局时间为确定性时间避免定时边界事件干扰断言。Camunda 提供 ClockUtil 的静态方法// 设置引擎内部时钟 ProcessEngine processEngine ProcessEngines.getDefaultProcessEngine(); processEngine.getProcessEngineConfiguration().getClock().setCurrentTime(new Date(2025/01/01 00:00:00));我自己的习惯是每个流程至少写通过、驳回、异常边界、超时四条路径这四条覆盖了大多数生产问题。4. 常见问题与排查技巧实录4.1 部署新版本后旧实例跑不动有朋友遇到这样的问题线上跑了很久的流程实例更新模型后所有新任务都不见了甚至流程实例挂起。排查后发现是因为部署新版本时改了流程 key或者把节点 key 给改了。Camunda 按节点 key 关联历史活动和任务所以一旦改动节点 id旧实例后续的节点映射就会失效。经验教训流程模型上线后节点 key 绝不能改。如果要改名字只改 name 属性不要改 id。如果一定要删除中间节点建议先评估在途实例或者通过流程迁移 API 将旧实例迁移到新定义前提是节点映射关系能在模型匹配上。流程定义版本的平滑切换是引擎最强大的能力也最容易因为不守规矩而引发故障。4.2 事务回滚与边界事件冲突服务任务中抛出 BpmnError 会被边界事件捕获这是一种业务异常处理路径。如果是抛出其他 Runtime 异常则引擎事务直接回滚流程实例状态回到进入服务任务前的状态。这里有个常见误解以为边界事件能捕获所有异常。实际上只有 BpmnError 会被捕获普通异常不会进入边界事件。所以在代码里务必明确区分业务失败和系统错误。针对支付失败这类业务异常使用 BpmnError针对返回 500 这种系统异常应当让事务回滚或者用异步 Job 重试机制。另外如果委托方法内捕获了异常并吞掉什么都不做那么服务任务就会被认为执行成功继续向下走这是最隐蔽的错误路径。生产日志里出现“流程实例莫名其妙就走完了”的情况多数是空 catch 导致的。4.3 历史表增长与性能优化Camunda 7 的历史表会随着流程实例数量线性增长尤其是 ACT_HI_VARINST变量历史表写得很频繁。如果系统每天跑上万个流程实例一个月后历史表可能达到几千万行查询会明显变慢。解决思路有三个方向。一是按时间定期清理历史数据Camunda 提供了历史清理机制通过配置历史清理策略可以只保留最近 90 天的历史数据。二是在部署流程时进行流程实例统计热点流程可以设置 historical activity 为不记录但尽量少做因为会丢掉排障数据。三是为常用查询添加索引特别是按 business_key、按 process_definition_key 的过滤条件。更彻底的架构手段是把历史数据做数据归档定期把 ACT_HI_ 表的数据转储到归档库并删除源库这样引擎库始终维持可控体积查询也不会被归档拖累。4.4 并发场景与集群部署的坑Camunda 7 默认以数据库行锁保证并发一致性。两个用户同时完成同一个任务时一个成功另一个会抛 PessimisticLockingFailureException原因是数据库行锁等待超时。表面上看起来像是偶发报错但其实是正常的并发保护。此时业务系统应该捕获该异常并提示用户“任务已被处理”而不是盲目重试。集群部署时Camunda 7 支持多节点共享数据库通过 Quartz Job Executor 抢占式执行异步任务。默认的 Job Executor 每个节点都会去抢但同一个 Job 在同一时间只能被一个节点执行数据库锁保证这一点。配置时要注意节点间系统时钟尽量一致否则定时任务的准时性会受到印象。Camunda 8Zeebe则没有这个问题它通过分区与 Leader 机制天然协调多节点执行。从运维角度说集群部署 Camunda 7 的核心是数据库的高可用不要为了追求引擎高可用而部署多个节点却忽略了数据库的单点风险。数据库挂了集群节点再多也白搭。5. 真实案例复盘一个审批流程的落地过程最后分享一个我在制造业项目里实际落地 Camunda 的简化版本供参考。业务场景是设备点检流程。设备每月需要点检由点检员填写点检单包含设备编号、点检项目、是否异常。如果设备异常需要创建维修工单由维修组长派工给维修工维修完成后验证人验证通过才闭环。异常信息还要同步到质量部门。我们使用 Camunda 7 部署了两个主要流程。第一个是“点检异常触发流程”由点检单创建事件触发流程如下开始事件消息事件 - 写入工单表服务任务 - 维修组长审批用户任务 - 并行分支一个分支推送通知给质量部另一个分支等待维修完成。在这套流程中我们用 DMN 决策表处理“什么样的异常需要立即停机”的规则。当异常设备涉及关键生产设备且异常级别为“严重”时决策表返回 true流程会启动一条紧急停机审批子流程否则只进入普通维修。这个设计很清楚地展示了 BPMN 处理流程编排、DMN 处理规则判断的好处业务代码里不再有复杂的 if 嵌套。实施中的关键时间点第一天引入依赖写好流程模型骨架第二天实现两个服务任务和用户任务的查询接口第三天完成联调包括边界事件、异常捕获。整体比用状态机写效率高很多因为和业务方讨论时是直接看流程图而不是翻代码。6. 写在最后的经验提醒我一直觉得工作流引擎的引入不是技术问题而是建模意识问题。Camunda 把流程可视化、自动化、版本化做得足够好但它不会替你想清楚每一步谁负责、条件怎么判、失败怎么降级。建模前花时间梳理业务规则比用任何高深 API 都重要。我在第一次用 Camunda 时以为把流程画出来就能跑后来发现流程图上多数节点只是表达“有人看一眼”而没有任何实际动作这种模型对业务没有正向价值。如果让我给一条最核心的建议从最小的端到端流程开始跑通后再逐步增加网关、边界事件、DMN 决策。不要一开始就在流程里塞并行网关和子流程否则你连最基础的贯穿链路都没验证就被并行分支和事务边界问题淹没了。踩过几次坑之后我现在更倾向于把“异常处理路径”放在最前面设计也就是先想清楚哪些环节会失败、失败之后往哪里走而不是先画主路径。主路径人人都能画真正体现工程能力的恰恰是那些不在主路径上的分支与补偿逻辑。
