简介面向Spring Boot 3.X开发者的Camunda工作流引擎整合源码包完整呈现一个多模块的new-workflow-engine实战项目适合需要快速在Spring Boot 3应用中集成Camunda的Java工程师。包体共87个文件涵盖17个XML配置、8个BPMN流程定义、7个Java核心类以及YAML、Markdown等说明文档压缩包仅1.17MB模块划分清晰便于按server/client分层研读。目前已有300人学习下载。源码包展示了从流程建模、引擎配置到服务调用的完整链路并附带Git版本记录与IDE配置读者可对照BPMN文件理解流程定义与Java代码的映射关系也可借助示例配置直接迁移到自身项目省去从零搭建与踩坑时间是掌握Spring Boot 3与Camunda整合的实用参考资料。 最近在折腾老中台项目升级原来的审批流跑在 SpringBoot 2.7 Camunda 7.15 上这回要一鼓作气升到 SpringBoot 3.x。卡了我两天的不是业务代码而是 Camunda 的兼容性问题SpringBoot 3 全量切到 Jakarta 命名空间后旧版 starter 直接用不了报错清一色是NoClassDefFoundError: javax/xml/bind/...。翻完官方兼容性矩阵再把流程文件、配置、任务接口全部调通后我决定把这次 SpringBoot 3.X 整合 Camunda 的完整过程写下来帮后面跳版本的朋友少走点弯路。1. 版本选型SpringBoot 3 时代别选错 Camunda 分支1.1 Camunda 7 和 Camunda 8 怎么选很多第一次接触 Camunda 的人会把 7 和 8 当成单纯的版本升级实际上这是两条技术路线。Camunda 8 是云原生架构核心引擎是 Zeebe独立部署 broker 集群虽然性能和水平扩展很强但对中后台单机应用来说太重了。Camunda 7 是经典嵌入式引擎能直接和 Spring Boot 应用打包在一个进程里启动快、运维简单现有团队的学习成本也低。这次整合我选的是 Camunda 7.20.0。从 7.20 开始官方 starter 完整支持 SpringBoot 3 和 Jakarta EE 9JDK 17 下跑得也算稳定。如果你的项目已经上了 SpringBoot 3.2我建议直接考虑 7.21 或更新的补丁版本没必要卡在 7.20 上。社区版虽然不提供企业级技术支持但版本迭代一直很及时踩到 Bug 的概率不高。1.2 版本匹配表与兼容性判断做升级前先对一张版本表这是我结合官方 release note 和实际测试整理出来的SpringBoot 版本推荐 Camunda 版本JDK备注3.0.x7.20.x17基础可用部分插件需自己适配3.1.x7.20.x / 7.21.x17组合最稳推荐使用3.2.x7.21.x17建议用官方测试过的配对版本判断一个 starter 能不能直接用的最快方法是看依赖里是否出现jakarta.*替换了javax.*。Camunda 7.19 还处在过渡期7.20 开始开源依赖已经切干净了。如果项目里还有旧的自定义插件需要重点检查是否引用了javax.persistence、javax.xml.bind这类被移到 Jakarta 下的包。2. Maven 依赖和最小接入工程2.1 最精简的 pom 依赖组合SpringBoot 3.x 整合 Camunda 最少需要三块流程引擎核心、Web starter、数据库驱动。我这里用的是camunda-bpm-spring-boot-starter-webapps它会把引擎、REST API 和 Camunda 自带的 Web 应用Cockpit、Tasklist一起带进来对开发本地调试非常方便。dependency groupIdorg.camunda.bpm.springboot/groupId artifactIdcamunda-bpm-spring-boot-starter-webapps/artifactId version7.20.0/version /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency这里有个容易踩的坑SpringBoot 3 里 MySQL 官方驱动已经改成com.mysql:mysql-connector-j老的mysql:mysql-connector-java坐标在新版依赖管理中很可能拉不到或者版本解析出问题。如果生产环境不需要 Camunda 自带的 Cockpit 和 Tasklist就改用camunda-bpm-spring-boot-starter然后自己写 REST 接口封装业务。两种方式的核心 API 完全一样后续切换成本不高。2.2 数据源连接配置注意点Camunda 需要一个独立数据库不会和业务库混在一起。我建议单独建一个camunda库并在application.yml里配置好数据源spring: datasource: url: jdbc:mysql://localhost:3306/camunda?useSSLfalsenullCatalogMeansCurrenttrue username: root password: root driver-class-name: com.mysql.cj.jdbc.Driver camunda: bpm: history-level: full auto-deployment-enabled: true database: schema-update: true type: mysqlMySQL 连接串里的nullCatalogMeansCurrenttrue一定要加否则 Camunda 在初始化时可能把表建到其他同名 catalog 下导致启动没报错但看不到任何引擎表。H2 环境下这个问题不明显一上 MySQL 就经常遇到。3. BPMN 流程文件的落盘与自动部署3.1 resources/processes 目录约定Camunda 的 SpringBoot starter 默认会扫描classpath:/processes目录把里面的.bpmn、.bpmn20.xml文件自动部署到引擎。这个机制很方便但很多人不知道部署版本是怎么管理的同一个流程 key 每次启动如果有变更都会生成一个新版本。所以开发环境我通常建议加一条启动参数控制自动部署避免每次重启刷一堆版本记录。完整路径配置可以这样覆盖camunda: bpm: deployment-resource-pattern: classpath:/processes/*.bpmn3.2 一个最简的请假审批流程 XML为了让后面讲 JavaDelegate 和任务查询时有具体承载对象我先写一个简单流程提交申请 - 主管审批 - 通知结果 - 结束。用 Camunda Modeler 画出来的 XML 大致是这样?xml version1.0 encodingUTF-8? bpmn:definitions xmlns:bpmnhttp://www.omg.org/spec/BPMN/20100524/MODEL xmlns:camundahttp://camunda.org/schema/1.0/bpmn targetNamespacehttp://example.com/leave bpmn:process idleaveProcess name请假审批 isExecutabletrue bpmn:startEvent idstart name提交申请 camunda:formKeyleave-apply bpmn:outgoingflow1/bpmn:outgoing /bpmn:startEvent bpmn:userTask idapproval name主管审批 camunda:assignee${applyUser} bpmn:incomingflow1/bpmn:incoming bpmn:outgoingflow2/bpmn:outgoing /bpmn:userTask bpmn:serviceTask idnotify name通知结果 camunda:delegateExpression${leaveNotify} bpmn:incomingflow2/bpmn:incoming bpmn:outgoingflow3/bpmn:outgoing /bpmn:serviceTask bpmn:endEvent idend name结束 bpmn:incomingflow3/bpmn:incoming /bpmn:endEvent bpmn:sequenceFlow idflow1 sourceRefstart targetRefapproval/ bpmn:sequenceFlow idflow2 sourceRefapproval targetRefnotify/ bpmn:sequenceFlow idflow3 sourceRefnotify targetRefend/ /bpmn:process /bpmn:definitions注意xmlns:camunda命名空间一定要带上camunda:delegateExpression、camunda:assignee才能生效。如果是第一次手写 XML建议先在 Camunda Modeler 里画好直接导出否则容易漏命名空间。3.3 自动部署的版本管理流程文件一旦部署Camunda 就会绑定processDefinitionKey。同一个 key 的新版本会保留历史版本业务上继续用startProcessInstanceByKey默认启动最新版本。如果希望指定旧版本可以用processDefinitionId启动。我在实际项目中习惯把流程文件版本写入文件名比如leave-v1.0.0.bpmn避免多分支开发时同名文件覆盖导致版本混乱。同时开发环境可以临时关闭自动部署本地改完流程文件后手动调用 RepositoryService 部署这样不会影响其他同事的开发数据。4. 核心配置项解析历史级别、权限开关和任务执行器4.1 history-level 选多少合适history-level决定 Camunda 存储多少历史信息直接关系到表的膨胀速度级别存储内容适用场景none不存历史几乎不用activity实例和活动实例数据只需要看流程走到哪audit上面全部 变量更新多数业务系统full上面全部 所有细节审计、排错、BI 分析我项目里因为要走审批报表选了 full。如果只关心流程节点状态用 audit 就够full 会多出不少变量历史记录长期运行占用空间不小。4.2 权限和过滤器开关SpringBoot 3 整合 Camunda 时最容易被忽略的是authorization-enabled和filter.createcamunda: bpm: authorization-enabled: false filter: create: false如果authorization-enabled设成 true那么连内置的 Cockpit 页面都会要求登录和权限配置开发阶段容易一头雾水。生产环境若要做权限控制我建议先关掉引擎内部权限在业务 API 层用自己的认证体系控制这样和 Spring Security 集成起来更自然。4.3 JobExecutor 与异步消息Camunda 里计时器、异步续接、外部任务都依赖 JobExecutor。SpringBoot 整合版本默认会自动启动不需要额外配置。如果生产环境实例很多可以把 JobExecutor 独立成线程池通过camunda.bpm.job-executor下的参数调整核心线程数、队列容量。这些参数一般不用动遇到性能瓶颈再拆。5. Java 服务类与流程引擎的衔接5.1 用 JavaDelegate 接业务逻辑流程文件里的serviceTask绑定的camunda:delegateExpression实际指向 Spring 容器里一个JavaDelegate实现类。这个类负责在节点执行时调用业务逻辑比如发通知、写状态Component(leaveNotify) public class LeaveNotifyDelegate implements JavaDelegate { Override public void execute(DelegateExecution execution) throws Exception { String applicant (String) execution.getVariable(applicant); Boolean approved (Boolean) execution.getVariable(approved); String message Boolean.TRUE.equals(approved) ? 您的请假申请已通过 : 您的请假申请未通过; execution.setVariable(message, message); } }有个细节如果该节点执行抛异常事务会回滚流程会停留在当前节点等待重试。这是 Camunda 一致性的关键别在 delegate 里 catch 完就吞掉异常否则流程状态会和企业实际业务状态不一致。5.2 统一入口启动流程实例启动流程实例通常封装在 Service 层用流程 key 加上业务参数Service public class LeaveService { private final RuntimeService runtimeService; private final TaskService taskService; public LeaveService(RuntimeService runtimeService, TaskService taskService) { this.runtimeService runtimeService; this.taskService taskService; } public String startLeave(String applicant, String applyUser, int days) { MapString, Object variables new HashMap(); variables.put(applicant, applicant); variables.put(applyUser, applyUser); variables.put(days, days); ProcessInstance instance runtimeService .startProcessInstanceByKey(leaveProcess, variables); return instance.getProcessInstanceId(); } }注意注入方式。我用的是构造器注入不想在 SpringBoot 3 里遇到循环依赖问题就别再写Autowired字段注入了。5.3 查询待办、认领和完成任务流程跑到userTask时会生成待办任务常见的操作是查询某人待办、认领和执行完成ListTask tasks taskService.createTaskQuery() .processDefinitionKey(leaveProcess) .taskAssignee(manager1) .orderByTaskCreateTime() .desc() .list(); if (!tasks.isEmpty()) { Task task tasks.get(0); String taskId task.getId(); taskService.setVariable(taskId, approved, true); taskService.complete(taskId); }complete方法会触发流程往下走同时会立刻执行后续没有异步配置的节点。如果计量器或网关后面的节点很多建议在流程设计阶段把耗时操作配置为camunda:asyncBeforetrue或camunda:asyncAftertrue避免单次请求里把大量逻辑都跑完拖长事务。6. 整合中的高频坑与排查技巧速查6.1 SpringBoot 3 循环依赖导致的启动失败升级到 SpringBoot 3 以后Spring 默认禁止循环依赖一旦工程里存在两个 Bean 互相引用启动直接失败。Camunda 的HistoryEventHandler、自定义JobHandler这类扩展点很容易写循环依赖报错日志的核心是这一句The dependencies of some of the beans in the application context form a cycle我的处理思路是先拆分职责把流程引擎扩展点单独抽到Configuration中依赖业务 Service 时通过ObjectProviderT懒加载获取而不是在构造器里直接注入。6.2 流程变量塞对象引发的序列化问题在流程变量里放自定义 POJO是很多人都会图省事做的事variables.put(leaveForm, new LeaveForm(...));但 Camunda 7.20 对 Java 原生序列化有包名白名单限制自定义类不在白名单里就会报ClassNotFoundException或拒绝序列化。最简单的方案是不要直接塞对象改成塞 JSON 字符串或 Mapvariables.put(leaveForm, Map.of( applicant, applicant, days, days ));如果确实要存对象可以引入 Camunda Spin 序列化器用 JSON 方式存流程变量这样引擎表和变量查询都更透明。6.3 历史数据表持续膨胀Camunda 默认会保留历史数据长时间运行后ACT_HI_*系列表会越积越大。我的做法是开启历史清理指定清理窗口和每批清理数量camunda: bpm: history-cleanup: enabled: true batch-window: start: 02:00 end: 04:00 batch-size: 500这样引擎的 JobExecutor 会在指定时间段自动清理超过保留天数的历史数据。开发环境如果不在乎历史量把history-level调成activity也能显著降低数据量。6.4 启动失败的排查清单异常现象可能原因解决办法找不到 javax.* 类Camunda 版本低于 7.20升级到适配 SpringBoot 3 的版本引擎表建到别的库MySQL 连接参数缺少 catalog 约束加上nullCatalogMeansCurrenttrueBPMN 文件部署报解析错误缺少 camunda 命名空间用 Camunda Modeler 打开校验Tasklist 页面 404只引了 core starter增加starter-webapps依赖节点执行时报类未找到JavaDelegate 类没有扫描到检查Component和包扫描路径最后还有个小技巧想分享不要光依赖自动部署。把流程文件纳入代码评审和版本管理和代码一起发版才是正确姿势。改流程定义时先在本地跑一遍引擎测试确认新版本流程的 XML 能通过校验再合到主干。毕竟工作流引擎是整个审批链路的发动机一旦流程文件发布出问题影响的不只是某一个服务而是所有在流程中跑来跑去的业务单据。本文还有配套的精品资源点击获取