📚 课程目录第3章环境搭建与初始化

3. 环境搭建与初始化：Spring Boot 集成 Flowable 引擎，数据库初始化配置

说实话，很多同学学流程引擎，上来就卡在环境搭建这一步。不是依赖冲突，就是数据库表起不来。我早期带团队的时候，光帮人排查集成问题就花了不少时间。今天咱们就把这一步走稳，把坑提前填上。

3.1 为什么选 Spring Boot + Flowable？

你想想看，现在做企业级应用，谁还不用个 Spring Boot？Flowable 作为轻量级流程引擎，跟 Spring Boot 的契合度非常高。我个人习惯是把 Flowable 当作一个“流程中间件”嵌入到业务系统里，而不是单独部署一套流程服务器。

核心优势：

Flowable 6.x+ 原生支持 Spring Boot 自动配置
流程定义、实例、任务全部存在业务库中，方便统一备份
不需要额外部署流程服务，减少运维成本

3.2 依赖引入与版本选择

这里有个坑，我先说。Flowable 的版本跟 Spring Boot 版本有对应关系。我曾经见过有人把 Flowable 6.6 配到 Spring Boot 3.0 上，结果启动直接报错。嗯，版本不对，啥都白费。

我建议你直接用这套组合：

组件	推荐版本	说明
Spring Boot	2.7.x	稳定，社区支持好
Flowable	6.7.2	与 2.7.x 完美兼容
MySQL	8.0+	生产环境推荐
MyBatis-Plus	3.5.x	可选，用于业务表操作

在 pom.xml 里，核心依赖就这几行：

<!-- Flowable Spring Boot Starter -->
<dependency>
    <groupId>org.flowable</groupId>
    <artifactId>flowable-spring-boot-starter</artifactId>
    <version>6.7.2</version>
</dependency>

<!-- 数据库驱动 -->
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <scope>runtime</scope>
</dependency>

<!-- 连接池（推荐 HikariCP，Spring Boot 默认） -->
<dependency>
    <groupId>com.zaxxer</groupId>
    <artifactId>HikariCP</artifactId>
</dependency>

小提示： 别一股脑把 flowable-spring-boot-starter-all 加进来。那个包会引入所有 Flowable 模块（包括不常用的 DMN、CMN）。用 starter 就够了，按需再加扩展模块。

3.3 数据库初始化配置

Flowable 启动时会自动检查数据库里有没有 ACT_ 开头的表。如果没有，它会根据配置自动建表。这个机制很方便，但第一次用的时候容易踩坑。

在 application.yml 里，核心配置如下：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/flowable_demo?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai&nullCatalogMeansCurrent=true
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5

flowable:
  # 数据库策略：true 表示启动时自动建表/升级
  database-schema-update: true
  # 关闭 Flowable 自带的 REST API（我们不用）
  rest-api-enabled: false
  # 异步执行器（生产环境建议开启）
  async-executor-activate: true

这里有个关键参数 nullCatalogMeansCurrent=true。为什么要加这个？

MySQL 8.0 之后，驱动行为变了。如果不加这个参数，Flowable 在检查表是否存在时会扫描所有库，导致误判。我遇到过好几次，明明表已经建了，Flowable 还认为没有，又去重建，结果报错。加上这个参数，它就只检查当前库。

3.4 启动验证：看看表都建了没

配置写好了，启动项目。如果一切正常，控制台会看到类似这样的日志：

2024-01-15 10:23:45.123  INFO 12345 --- [main] o.f.spring.boot.FlowableServletAutoConfiguration : 
Flowable Engine started. Tables checked: 28

然后去数据库里看一眼，应该能看到这些表：

表前缀	用途	核心表举例
ACT_RE_*	流程定义、模型等静态资源	ACT_RE_PROCDEF, ACT_RE_DEPLOYMENT
ACT_RU_*	运行时数据（流程实例、任务、变量）	ACT_RU_EXECUTION, ACT_RU_TASK
ACT_HI_*	历史数据（已完成的流程、任务）	ACT_HI_PROCINST, ACT_HI_TASKINST
ACT_GE_*	通用数据（如字节数组、属性）	ACT_GE_BYTEARRAY, ACT_GE_PROPERTY

一共 28 张表（不同版本略有差异）。如果你看到的是 0 张，那说明配置没生效。检查一下 database-schema-update 是不是被覆盖了。

注意： 生产环境不要用 database-schema-update: true。这个配置在启动时会检查表结构并自动执行 DDL，有锁表风险。生产环境应该用脚本手动执行建表，或者用 Flyway/Liquibase 管理。

3.5 核心流程引擎 API 的初始化

表建好了，引擎也启动了。接下来我们看看怎么拿到 Flowable 的核心 API。Spring Boot 自动配置会帮我们注入这些 Bean：

@Service
public class FlowableService {

    // 流程引擎入口
    @Autowired
    private ProcessEngine processEngine;

    // 运行时服务（启动流程、操作任务）
    @Autowired
    private RuntimeService runtimeService;

    // 任务服务（查询、完成、认领任务）
    @Autowired
    private TaskService taskService;

    // 仓库服务（部署流程定义）
    @Autowired
    private RepositoryService repositoryService;

    // 历史服务（查询已完成的流程）
    @Autowired
    private HistoryService historyService;

    // 身份服务（用户、组管理）
    @Autowired
    private IdentityService identityService;
}

这些服务就是咱们后面写审批流逻辑的“工具箱”。说白了，流程引擎就是靠这几个 Service 来驱动的。

3.6 快速验证：部署一条最简单的流程

为了确认环境真的通了，我习惯写一个简单的测试。部署一条只有一个“开始→结束”的流程定义：

@SpringBootTest
class FlowableInitTest {

    @Autowired
    private RepositoryService repositoryService;

    @Autowired
    private RuntimeService runtimeService;

    @Test
    void testDeployAndStart() {
        // 1. 部署流程定义（BPMN 文件放在 resources/processes/ 下）
        Deployment deployment = repositoryService.createDeployment()
                .addClasspathResource("processes/simple-approval.bpmn20.xml")
                .name("简单审批流程")
                .deploy();

        System.out.println("部署ID: " + deployment.getId());

        // 2. 启动流程实例
        ProcessInstance processInstance = runtimeService
                .startProcessInstanceByKey("simpleApproval");

        System.out.println("流程实例ID: " + processInstance.getId());
        System.out.println("环境搭建成功！");
    }
}

跑一下这个测试。如果控制台打印出部署ID和流程实例ID，恭喜你，环境搭好了。

避坑指南： 我曾经遇到过 BPMN 文件放在 resources 下但没被扫描到的情况。检查一下 flowable.process-definition-location-prefix 配置，默认是 classpath*:/processes/。如果你改了路径，记得同步更新。

3.7 整体架构图

下面这张图，是我自己画的环境搭建整体架构。你可以对照着检查自己的配置：

从这张图可以看得很清楚：Spring Boot 启动后，Flowable 自动配置会初始化 ProcessEngine，然后通过数据源连接 MySQL，自动创建 28 张流程表。后面我们所有的流程操作，都是基于这四类表来完成的。

3.8 常见问题排查

最后，我把这些年遇到的环境搭建问题整理了一下。你如果启动报错，先对照这个表查：

错误现象	原因	解决方案
启动报 `Table 'ACT_GE_PROPERTY' doesn't exist`	数据库连接串没加 `nullCatalogMeansCurrent=true`	在 JDBC URL 末尾加上该参数
控制台打印 `Tables checked: 0`	`database-schema-update` 被设置为 false 或未生效	检查 yml 配置，确认没有其他地方覆盖
启动报 `DataSource 不可用`	MySQL 连接超时或密码错误	先单独测一下数据库连接是否正常
部署 BPMN 文件报 `资源未找到`	文件没放在 `resources/processes/` 下	检查路径，或者用路径部署