企业官网建设流程全解析

简介：面向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 9+，JDK 17 下跑得也算稳定。如果你的项目已经上了 SpringBoot 3.2，我建议直接考虑 7.21 或更新的补丁版本，没必要卡在 7.20 上。社区版虽然不提供企业级技术支持，但版本迭代一直很及时，踩到 Bug 的概率不高。

1.2 版本匹配表与兼容性判断

做升级前先对一张版本表，这是我结合官方 release note 和实际测试整理出来的：

判断一个 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> <groupId>org.camunda.bpm.springboot</groupId> <artifactId>camunda-bpm-spring-boot-starter-webapps</artifactId> <version>7.20.0</version> </dependency> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</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?useSSL=false&nullCatalogMeansCurrent=true 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: mysql

MySQL 连接串里的nullCatalogMeansCurrent=true一定要加，否则 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/*.bpmn

3.2 一个最简的请假审批流程 XML

为了让后面讲 JavaDelegate 和任务查询时有具体承载对象，我先写一个简单流程：提交申请 -> 主管审批 -> 通知结果 -> 结束。用 Camunda Modeler 画出来的 XML 大致是这样：

<?xml version="1.0" encoding="UTF-8"?> <bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:camunda="http://camunda.org/schema/1.0/bpmn" targetNamespace="http://example.com/leave"> <bpmn:process id="leaveProcess" name="请假审批" isExecutable="true"> <bpmn:startEvent id="start" name="提交申请" camunda:formKey="leave-apply"> <bpmn:outgoing>flow1</bpmn:outgoing> </bpmn:startEvent> <bpmn:userTask id="approval" name="主管审批" camunda:assignee="${applyUser}"> <bpmn:incoming>flow1</bpmn:incoming> <bpmn:outgoing>flow2</bpmn:outgoing> </bpmn:userTask> <bpmn:serviceTask id="notify" name="通知结果" camunda:delegateExpression="${leaveNotify}"> <bpmn:incoming>flow2</bpmn:incoming> <bpmn:outgoing>flow3</bpmn:outgoing> </bpmn:serviceTask> <bpmn:endEvent id="end" name="结束"> <bpmn:incoming>flow3</bpmn:incoming> </bpmn:endEvent> <bpmn:sequenceFlow id="flow1" sourceRef="start" targetRef="approval"/> <bpmn:sequenceFlow id="flow2" sourceRef="approval" targetRef="notify"/> <bpmn:sequenceFlow id="flow3" sourceRef="notify" targetRef="end"/> </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 存储多少历史信息，直接关系到表的膨胀速度：

我项目里因为要走审批报表，选了 full。如果只关心流程节点状态，用 audit 就够，full 会多出不少变量历史记录，长期运行占用空间不小。

4.2 权限和过滤器开关

SpringBoot 3 整合 Camunda 时，最容易被忽略的是authorization-enabled和filter.create：

camunda: 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) { Map<String, 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时会生成待办任务，常见的操作是查询某人待办、认领和执行完成：

List<Task> 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:asyncBefore="true"或camunda:asyncAfter="true"，避免单次请求里把大量逻辑都跑完，拖长事务。

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 时通过ObjectProvider<T>懒加载获取，而不是在构造器里直接注入。

6.2 流程变量塞对象引发的序列化问题

在流程变量里放自定义 POJO，是很多人都会图省事做的事：

variables.put("leaveForm", new LeaveForm(...));

但 Camunda 7.20 对 Java 原生序列化有包名白名单限制，自定义类不在白名单里就会报ClassNotFoundException或拒绝序列化。最简单的方案是不要直接塞对象，改成塞 JSON 字符串或 Map：

variables.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 启动失败的排查清单

最后还有个小技巧想分享：不要光依赖自动部署。把流程文件纳入代码评审和版本管理，和代码一起发版才是正确姿势。改流程定义时，先在本地跑一遍引擎测试，确认新版本流程的 XML 能通过校验，再合到主干。毕竟工作流引擎是整个审批链路的发动机，一旦流程文件发布出问题，影响的不只是某一个服务，而是所有在流程中跑来跑去的业务单据。

本文还有配套的精品资源，点击获取