SpringBoot集成Camunda工作流引擎实战-代码聚汇网

SpringBoot集成Camunda工作流引擎实战

SpringBootCamunda工作流引擎

|难度：普通|阅读约 31 分钟

1. 项目概述

最近在做一个内部审批系统升级，需要引入工作流引擎来规范业务流程。经过技术选型，最终决定采用SpringBoot 2.7.15 + MySQL 8 + Camunda这套技术栈。这个组合在实际项目中表现相当稳定，特别是Camunda作为Activiti的衍生版本，在流程可视化和管理方面有着明显优势。

这个技术栈特别适合需要快速实现业务流程自动化的场景，比如OA系统、订单审批、财务报销等典型工作流应用。SpringBoot提供了简洁的框架基础，MySQL 8在JSON支持和性能上的改进对工作流存储很友好，而Camunda则带来了专业级的流程引擎能力。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 环境准备与依赖配置

2.1 基础环境搭建

首先确保开发环境已经安装：

JDK 1.8或以上版本
MySQL 8.0+数据库
Maven 3.6+

MySQL 8的安装有几个关键点需要注意：

安装时建议选择"Developer Default"配置
设置密码加密方式为mysql_native_password，避免连接问题
配置innodb_buffer_pool_size为物理内存的50-70%

提示：MySQL 8默认使用caching_sha2_password认证，如果遇到客户端连接问题，可以通过ALTER USER语句修改认证方式。

2.2 Maven依赖配置

在pom.xml中添加核心依赖：

xml复制<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>2.7.15</version>
</dependency>
<dependency>
    <groupId>org.camunda.bpm.springboot</groupId>
    <artifactId>camunda-bpm-spring-boot-starter</artifactId>
    <version>7.18.0</version>
</dependency>
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>
</dependency>

特别注意版本兼容性：

Camunda 7.18.x 完美支持SpringBoot 2.7.x
MySQL Connector/J 8.x 是必须的，5.x版本无法完全支持MySQL 8的特性

3. 数据库配置与初始化

3.1 数据库连接配置

application.yml中的关键配置：

yaml复制spring:
  datasource:
    url: jdbc:mysql://localhost:3306/camunda_db?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true
    username: camunda
    password: camunda
    driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: true

camunda.bpm:
  admin-user:
    id: admin
    password: admin
    firstName: Admin
  filter:
    create: All tasks
  database:
    schema-update: true
    type: mysql

几个关键配置说明：

serverTimezone=UTC 避免时区问题
allowPublicKeyRetrieval=true 解决MySQL 8连接时的SSL问题
ddl-auto: validate 确保数据库结构与实体一致

3.2 数据库初始化脚本

Camunda需要特定的表结构，官方提供了SQL脚本：

下载camunda-sql-scripts-7.18.0.zip
执行mysql-8.0目录下的create和init脚本
建议按这个顺序执行：
- engine_7.18.0_mysql.sql
- identity_7.18.0_mysql.sql
- admin_7.18.0_mysql.sql

实测发现：MySQL 8执行这些脚本时，可能需要临时关闭STRICT_TRANS_TABLES模式，否则某些字段定义会报错。

4. 基础流程设计与实现

4.1 简单审批流程设计

我们以一个请假审批流程为例，使用Camunda Modeler设计BPMN：

开始事件 → 用户任务(提交申请) → 独占网关 →
- 条件分支(天数≤3)→用户任务(经理审批)→结束事件
- 条件分支(天数>3)→用户任务(总监审批)→结束事件

保存为leave-approval.bpmn文件，放在resources/processes目录下。

4.2 SpringBoot集成配置

添加Camunda配置类：

java复制@Configuration
public class CamundaConfig {
    
    @Bean
    public ProcessEngine processEngine(ProcessEngineFactoryBean factory) {
        return factory.getObject();
    }
    
    @Bean
    public RepositoryService repositoryService(ProcessEngine processEngine) {
        return processEngine.getRepositoryService();
    }
    
    @Bean
    public RuntimeService runtimeService(ProcessEngine processEngine) {
        return processEngine.getRuntimeService();
    }
}

4.3 流程部署与启动

在服务启动时自动部署流程：

java复制@Component
public class ProcessDeployer {
    
    @Autowired
    private RepositoryService repositoryService;
    
    @PostConstruct
    public void deployProcess() {
        Deployment deployment = repositoryService.createDeployment()
            .addClasspathResource("processes/leave-approval.bpmn")
            .name("LeaveApprovalProcess")
            .deploy();
        System.out.println("Deployed process: "+deployment.getId());
    }
}

5. 业务逻辑实现

5.1 流程启动接口

创建REST接口启动流程：

java复制@RestController
@RequestMapping("/api/process")
public class ProcessController {
    
    @Autowired
    private RuntimeService runtimeService;
    
    @PostMapping("/start")
    public String startProcess(@RequestBody Map<String, Object> variables) {
        ProcessInstance instance = runtimeService.startProcessInstanceByKey(
            "LeaveApproval", 
            variables
        );
        return "Process started: "+instance.getId();
    }
}

5.2 任务处理服务

实现任务查询和完成逻辑：

java复制@Service
public class TaskService {
    
    @Autowired
    private TaskService camundaTaskService;
    
    public List<Task> getUserTasks(String userId) {
        return camundaTaskService.createTaskQuery()
            .taskAssignee(userId)
            .list();
    }
    
    public void completeTask(String taskId, Map<String, Object> variables) {
        camundaTaskService.complete(taskId, variables);
    }
}

5.3 业务规则集成

在网关条件中使用Spring Bean：

java复制@Component
public class LeaveApprovalRules {
    
    public boolean isShortLeave(int days) {
        return days <= 3;
    }
}

然后在流程定义中引用：

xml复制<sequenceFlow id="flow1" sourceRef="gateway" targetRef="managerTask">
  <conditionExpression xsi:type="tFormalExpression">
    ${leaveApprovalRules.isShortLeave(days)}
  </conditionExpression>
</sequenceFlow>

6. 常见问题与解决方案

6.1 数据库连接问题

问题现象：启动时报"Public Key Retrieval is not allowed"

解决方案：

在JDBC URL中添加allowPublicKeyRetrieval=true

或者修改MySQL用户认证方式：

sql复制ALTER USER 'camunda'@'%' IDENTIFIED WITH mysql_native_password BY 'password';

6.2 流程定义问题

问题现象：部署流程时报"unknown property 'id'"

解决方案：

检查BPMN文件是否使用Camunda Modeler创建
确保xmlns:camunda="http://camunda.org/schema/1.0/bpmn"命名空间正确定义

6.3 任务查询问题

问题现象：查询不到预期的任务

排查步骤：

检查ACT_RU_TASK表是否有对应记录
确认任务assignee或candidateUser设置正确
检查流程实例是否正常运行(ACT_RU_EXECUTION)

7. 性能优化建议

7.1 数据库优化

为常用查询字段添加索引：
- ACT_RU_TASK(ASSIGNEE_, PROC_INST_ID_)
- ACT_HI_TASK_INST(PROC_INST_ID_, END_TIME_)

配置连接池参数：

yaml复制spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      idle-timeout: 30000

7.2 流程设计优化

避免过多的嵌套子流程
对高频调用的服务任务使用异步特性(async=true)
考虑使用执行监听器替代JavaDelegate实现简单逻辑

7.3 缓存配置

启用历史级别缓存：

yaml复制camunda.bpm:
  generic-properties:
    properties:
      historyLevel: full
      databaseTablePrefix: ACT_
      jobExecutorActivate: true

8. 扩展功能实现

8.1 动态表单集成

使用Camunda表单引擎：

在BPMN中定义formKey：

xml复制<userTask id="approveTask" name="审批" camunda:formKey="approveForm">

创建表单定义文件approveForm.form：

json复制{
  "key": "approveForm",
  "components": [
    {
      "type": "text",
      "label": "审批意见",
      "key": "comment"
    }
  ]
}

8.2 邮件通知集成

配置邮件服务：

yaml复制camunda.bpm:
  mail:
    server:
      host: smtp.example.com
      port: 587
      username: user@example.com
      password: password
    default-sender: workflow@company.com

在流程中使用邮件任务：

xml复制<serviceTask id="sendMail" camunda:type="mail">
  <extensionElements>
    <camunda:field name="to" stringValue="${applicantEmail}" />
    <camunda:field name="subject" stringValue="请假审批结果" />
    <camunda:field name="text">
      <camunda:expression>
        Your leave request for ${days} days has been ${approved ? 'approved' : 'rejected'}
      </camunda:expression>
    </camunda:field>
  </extensionElements>
</serviceTask>

8.3 多租户支持

配置多租户数据源：

java复制@Bean
public MultiTenantProcessEngineConfiguration processEngineConfiguration() {
    MultiTenantProcessEngineConfiguration config = new SpringProcessEngineConfiguration();
    config.setTenantCheckEnabled(true);
    config.setDatabaseTablePrefix("${tenant.id}_ACT_");
    return config;
}

部署流程时指定租户：

java复制repositoryService.createDeployment()
    .tenantId("tenant1")
    .addClasspathResource("processes/process.bpmn")
    .deploy();

9. 监控与管理

9.1 内置管理界面

启用Camunda Webapps：

xml复制<dependency>
    <groupId>org.camunda.bpm.webapp</groupId>
    <artifactId>camunda-webapp</artifactId>
    <classifier>classes</classifier>
    <version>7.18.0</version>
</dependency>

访问路径：

Cockpit: /camunda/app/cockpit
Tasklist: /camunda/app/tasklist
Admin: /camunda/app/admin

9.2 SpringBoot Admin集成

添加依赖：

xml复制<dependency>
    <groupId>de.codecentric</groupId>
    <artifactId>spring-boot-admin-starter-client</artifactId>
    <version>2.7.10</version>
</dependency>

配置端点暴露：

yaml复制management:
  endpoints:
    web:
      exposure:
        include: "*"
  endpoint:
    health:
      show-details: always

9.3 自定义监控指标

暴露流程引擎指标：

java复制@Bean
public MeterBinder processEngineMetrics(ProcessEngine processEngine) {
    return new CamundaProcessEngineMetrics(processEngine);
}

在Prometheus中监控关键指标：

camunda_job_executor_active_threads
camunda_process_instances_running
camunda_tasks_created

10. 测试策略

10.1 单元测试配置

使用Camunda测试支持：

java复制@SpringBootTest
@RunWith(SpringRunner.class)
@Deployment(resources = "processes/leave-approval.bpmn")
public class ProcessTest {
    
    @Autowired
    private RuntimeService runtimeService;
    
    @Autowired
    private TaskService taskService;
    
    @Test
    public void testShortLeaveApproval() {
        Map<String, Object> vars = new HashMap<>();
        vars.put("days", 2);
        vars.put("applicant", "user1");
        
        ProcessInstance instance = runtimeService
            .startProcessInstanceByKey("LeaveApproval", vars);
        
        Task task = taskService.createTaskQuery()
            .processInstanceId(instance.getId())
            .singleResult();
        
        assertEquals("经理审批", task.getName());
    }
}

10.2 集成测试建议

使用Testcontainers进行数据库测试：

java复制@Testcontainers
@SpringBootTest
public class IntegrationTest {
    
    @Container
    static MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0");
    
    @DynamicPropertySource
    static void registerPgProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", mysql::getJdbcUrl);
        registry.add("spring.datasource.username", mysql::getUsername);
        registry.add("spring.datasource.password", mysql::getPassword);
    }
}

模拟用户任务交互：

java复制@Test
public void testCompleteApproval() {
    // 启动流程
    ProcessInstance instance = runtimeService
        .startProcessInstanceByKey("LeaveApproval", vars);
    
    // 模拟经理审批
    Task task = taskService.createTaskQuery()
        .taskAssignee("manager")
        .singleResult();
    
    Map<String, Object> taskVars = new HashMap<>();
    taskVars.put("approved", true);
    taskService.complete(task.getId(), taskVars);
    
    // 验证流程结束
    assertNull(runtimeService.createProcessInstanceQuery()
        .processInstanceId(instance.getId())
        .singleResult());
}

10.3 性能测试要点

使用JMeter测试并发流程启动
监控数据库连接池使用情况
关注历史数据表(ACT_HI_*)的增长速度
测试长时间运行流程的内存占用

11. 部署方案

11.1 开发环境部署

使用Docker Compose快速搭建：

yaml复制version: '3'
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: camunda
      MYSQL_USER: camunda
      MYSQL_PASSWORD: camunda
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
      
  app:
    build: .
    ports:
      - "8080:8080"
    depends_on:
      - mysql
      
volumes:
  mysql_data:

11.2 生产环境建议

数据库分离部署，配置主从复制
使用Nginx反向代理Camunda Webapps

配置适当的JVM参数：

code复制-Xms2g -Xmx2g -XX:MaxMetaspaceSize=512m

启用Camunda历史数据归档策略

11.3 Kubernetes部署

示例Deployment配置：

yaml复制apiVersion: apps/v1
kind: Deployment
metadata:
  name: workflow-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: workflow
  template:
    metadata:
      labels:
        app: workflow
    spec:
      containers:
      - name: app
        image: workflow-service:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: SPRING_DATASOURCE_URL
          value: jdbc:mysql://mysql-cluster:3306/camunda

12. 项目经验总结

在实际开发中，有几个关键点值得特别注意：

流程版本控制：Camunda的流程定义是版本化的，部署新版本时，正在运行的旧版本实例会继续使用旧定义。要特别注意流程变更的兼容性。
事务边界：Camunda的操作默认都在事务中执行，与Spring事务管理器配合时要特别注意事务传播行为。曾经遇到过一个案例：在@Transactional方法中启动流程，然后业务逻辑失败回滚，但流程实例已经创建，导致数据不一致。
历史数据清理：生产环境运行一段时间后，历史表(ACT_HI_*)会变得非常大。我们最终实现了定时任务，定期清理超过3个月的历史数据：

java复制@Scheduled(cron = "0 0 2 * * ?")
public void cleanHistory() {
    historyService.createHistoricProcessInstanceQuery()
        .finishedBefore(DateUtils.addDays(new Date(), -90))
        .list()
        .forEach(pi -> historyService.deleteHistoricProcessInstance(pi.getId()));
}

表单设计经验：对于复杂表单，推荐使用外置表单(通过formKey引用)而不是嵌入式表单。这样可以在不重新部署流程的情况下更新表单。
性能监控：我们为关键流程添加了执行时间监控：

java复制@Around("execution(* org.camunda.bpm.engine..*.*(..))")
public Object monitorEngineMethods(ProceedingJoinPoint pjp) throws Throwable {
    long start = System.currentTimeMillis();
    try {
        return pjp.proceed();
    } finally {
        long duration = System.currentTimeMillis() - start;
        metrics.recordEngineCall(pjp.getSignature().getName(), duration);
    }
}

这套技术栈经过多个项目验证，特别适合需要快速实现复杂业务流程的中大型系统。Camunda的学习曲线相对平缓，配合SpringBoot可以快速产出价值。对于需要更高性能的场景，可以考虑调整引擎配置，如增加异步执行器的线程数，或者对历史日志采用更精简的级别配置。