Spring Boot集成Flowable全流程实战指南
发布时间：2026/9/16 16:17:12 作者：尧图编辑部 阅读量：1,286
简介本资源是一套开箱即用的 Spring Boot Flowable 流程引擎集成项目面向 Java 后端开发者及工作流系统学习者解决流程自动化开发中引擎嵌入、可视化建模与快速启动等核心痛点。项目完整包含 Flowable Modeler 前端设计器、后端流程引擎配置、数据库自动建表逻辑及配套使用说明文档适用于审批流、任务调度、OA 系统等典型业务场景。压缩包共1500个文件以416个JS和296个HTML支撑Modeler前端交互342个PNG与20个SVG提供界面图标资源202个gz为前端依赖压缩包7个Java类如App、FlowUserController、ProcessEngineConfig构成核心后端骨架整体体积12.47MB结构清晰、模块分离度高。目前已有3382人学习下载读者可直接导入IDE运行获得可调试的全流程环境、标准化配置模板、内置流程示例及关键类注释完备的源码参考。1. Flowable Spring Boot 不是“加个依赖就能跑”它是一套可落地的流程治理基础设施很多开发者第一次接触 Flowable以为只是把flowable-spring-boot-starter塞进pom.xml再写个Bean ProcessEngine就完事了——结果启动报错Table ACT_RE_PROCDEF doesnt exist或者访问/modeler返回 404甚至流程部署后节点不触发、任务查不到。这不是配置漏了而是没理解 Flowable 在 Spring Boot 中的真实角色它不是单点组件而是一套包含流程定义管理Repository、运行时执行Runtime、任务调度Task、历史归档History和可视化建模Modeler的完整工作流基础设施。本项目正是将这五层能力在 Spring Boot 2.7 环境下做了一次端到端对齐——从数据库自动建表、REST API 暴露、前端 Modeler 嵌入到用户权限隔离FlowUserController、自定义 stencil 资源FlowableStencilSetResource全部开箱即用。适合需要快速构建审批流、工单系统、合同签署链路等业务场景的中后台团队尤其对已使用 Spring Security 或需对接现有用户体系的项目比直接部署独立 Flowable UI 更可控、更易审计。2. 从零启动Spring Boot 集成 Flowable 的四层初始化逻辑与关键配置项Flowable 在 Spring Boot 中的启动不是线性过程而是分层触发的数据层 → 引擎层 → Web 层 → Modeler 前端层。每一层都依赖前一层的就绪状态跳过任一环节都会导致后续功能失效。本项目通过ProcessEngineConfig.class和ApplicationConfiguration.class显式拆解了这四层并在AppDispatcherServletConfiguration.class中完成路径路由绑定。下面逐层说明其设计意图与实操要点。2.1 数据层自动建表背后的 DDL 控制权必须收归应用侧Flowable 默认通过spring.flowable.database-schema-updatetrue触发 H2 内存库建表但生产环境必须用 MySQL/PostgreSQL且表结构需受版本控制。本项目采用显式DatabaseAutoConfiguration.class核心逻辑如下Configuration public class DatabaseAutoConfiguration { Bean ConditionalOnMissingBean public DataSource dataSource() { HikariDataSource ds new HikariDataSource(); ds.setJdbcUrl(jdbc:mysql://localhost:3306/myflow?useSSLfalseserverTimezoneAsia/Shanghai); ds.setUsername(root); // ← 必须按 application.properties 动态注入 ds.setPassword(123456); ds.setDriverClassName(com.mysql.cj.jdbc.Driver); return ds; } Bean ConditionalOnMissingBean public PlatformTransactionManager transactionManager(DataSource dataSource) { return new DataSourceTransactionManager(dataSource); } }提示application.properties中的spring.datasource.*配置会覆盖dataSource()方法中的硬编码值但spring.flowable.database-schema-updatenone必须显式设置否则 Flowable 启动时会尝试 ALTER TABLE与 Flyway/Liquibase 冲突。本项目默认设为true是为新手友好实际项目应改为false并用 SQL 脚本初始化。Flowable 所需的 27 张表分为 5 类ACT_GE_*,ACT_RU_*,ACT_HI_*,ACT_ID_*,ACT_PROCDEF_*其中ACT_RE_PROCDEF流程定义、ACT_RU_EXECUTION运行实例、ACT_RU_TASK待办任务是高频操作表。建表失败常见原因有二一是 MySQL 8.0 默认sql_mode含STRICT_TRANS_TABLES导致 Flowable 的TEXT字段缺DEFAULT NULL报错二是字符集未统一为utf8mb4。解决方案是在application.properties中追加spring.datasource.hikari.connection-init-sqlSET NAMES utf8mb4; spring.jpa.properties.hibernate.dialectorg.hibernate.dialect.MySQL8Dialect2.2 引擎层ProcessEngineConfig 如何规避线程安全与 Bean 冲突陷阱ProcessEngineConfig.class不仅声明ProcessEngineBean更关键的是处理三个隐性风险多引擎实例冲突Spring Boot 默认注册ProcessEngine、RepositoryService、RuntimeService等单例 Bean若项目中存在多个Configuration类重复声明会导致NoSuchBeanDefinitionException事务传播失效Flowable 的runtimeService.startProcessInstanceByKey()必须运行在Transactional方法内否则流程实例无法持久化异步任务线程池失控asyncExecutor若未定制会使用Executors.newFixedThreadPool(3)在高并发任务场景下成为瓶颈。本项目的ProcessEngineConfig通过以下方式加固Bean ConditionalOnMissingBean public ProcessEngine processEngine(ProcessEngineConfiguration processEngineConfiguration) { // 关键禁用 Flowable 自动注册 Service Bean由 Spring 容器统一管理 processEngineConfiguration.setCreateDiagramOnDeploy(false); // 减少 PNG 生成开销 processEngineConfiguration.setAsyncExecutorActivate(false); // 关闭默认异步执行器 return processEngineConfiguration.buildProcessEngine(); } Bean ConditionalOnMissingBean public SpringProcessEngineConfiguration springProcessEngineConfiguration( DataSource dataSource, PlatformTransactionManager transactionManager, ObjectMapper objectMapper) { SpringProcessEngineConfiguration config new SpringProcessEngineConfiguration(); config.setDataSource(dataSource); config.setTransactionManager(transactionManager); config.setDatabaseSchemaUpdate(true); // 与 application.properties 保持一致 config.setDeploymentMode(default); config.setHistoryLevel(HistoryLevel.FULL); // 生产环境建议设为 AUDIT // 注入自定义 ObjectMapper解决 LocalDateTime 序列化问题 config.setObjectMapper(objectMapper); // 显式配置异步执行器替代默认 FixedThreadPool AsyncExecutor asyncExecutor new DefaultAsyncExecutor(); asyncExecutor.setCorePoolSize(5); asyncExecutor.setMaxPoolSize(20); asyncExecutor.setQueueSize(100); config.setAsyncExecutor(asyncExecutor); return config; }注意setAsyncExecutorActivate(false)表示不自动启动线程池需在processEngine创建后手动调用asyncExecutor.start()。本项目未启用异步任务故设为false若需定时任务如边界定时事件应在App.java的PostConstruct方法中启动。2.3 Web 层REST API 路由与 Modeler 前端资源的路径映射原理Flowable 提供flowable-ui-modeler作为独立 WAR 包但本项目选择嵌入式集成——将 Modeler 前端静态资源HTML/JS/CSS打包进src/main/resources/static/flow/并通过AppDispatcherServletConfiguration.class绑定/flow/**路径。该类本质是重写WebMvcConfigurer的addResourceHandlersConfiguration public class AppDispatcherServletConfiguration implements WebMvcConfigurer { Override public void addResourceHandlers(ResourceHandlerRegistry registry) { // 将 /flow/** 请求映射到 classpath:/static/flow/ 目录 registry.addResourceHandler(/flow/**) .addResourceLocations(classpath:/static/flow/); // 同时暴露 Flowable REST API/api/... registry.addResourceHandler(/api/**) .addResourceLocations(classpath:/static/api/); } }但仅配置静态资源还不够。Modeler 页面发起的/api/repository/deployments等请求需由 Flowable 的RestResponseFactory处理。本项目通过FlowableStencilSetResource.class实现自定义 stencil图形符号集其作用是让 Modeler 加载时读取stencilset.json并渲染符合企业规范的节点图标如“法务审核”“财务复核”。该类继承AbstractStencilSetResource重写getStencilSetInputStream()方法Component public class FlowableStencilSetResource extends AbstractStencilSetResource { Override protected InputStream getStencilSetInputStream() throws IOException { // 从 classpath 加载自定义 stencilset.json return this.getClass().getClassLoader() .getResourceAsStream(stencilset.json); } }关键参数说明stencilset.json中groups定义节点分类如 BPMN、Customshapes定义每个节点的 SVG 图标、属性面板字段propertyPackages。若未提供此文件Modeler 将加载默认 BPMN 2.0 stencil无法支持企业级流程图元扩展。3. Modeler 可视化设计器深度用法从流程建模到部署验证的闭环操作访问http://127.0.0.1:8081/flow进入 Modeler 后界面左侧为节点工具栏中间为画布右侧为属性面板。但多数人卡在第一步点击 “New Model” 后创建的.bpmn文件无法保存或部署。根本原因在于 Modeler 与后端 REST API 的鉴权与路径未对齐。本项目通过FlowUserController.class实现轻量级用户认证确保/api/*接口可被 Modeler 调用。3.1 用户登录与权限控制FlowUserController 如何实现最小可行认证FlowUserController.class并非完整 RBAC 系统而是提供/api/login接口返回 JWT Token并在SecurityConfig.class未在标题列出但实际存在中配置HttpSecurity放行/api/**路径RestController RequestMapping(/api) public class FlowUserController { PostMapping(/login) public ResponseEntityMapString, String login(RequestBody LoginRequest request) { // 简单校验生产环境应对接 Spring Security if (admin.equals(request.getUsername()) 123456.equals(request.getPassword())) { MapString, String response new HashMap(); response.put(token, fake-jwt-token-for-dev); response.put(user, admin); return ResponseEntity.ok(response); } return ResponseEntity.status(401).build(); } public static class LoginRequest { private String username; private String password; // getter/setter } }Modeler 前端在app.js中读取该 Token 并附加到所有/api/请求头// flow/static/flow/app.js 片段 var token localStorage.getItem(flowable-token); if (token) { $.ajaxSetup({ headers: { Authorization: Bearer token } }); }注意此方案仅用于开发验证。生产环境必须替换为 Spring Security OAuth2 或 JWT 全链路鉴权否则 Modeler 的/api/repository/deployments接口将 401 拒绝。3.2 流程建模实战三步完成请假流程并验证部署结果以“员工请假”为例演示从建模到运行的完整链路步骤 1创建 BPMN 模型并保存点击左上角 “New Model”输入名称leave-process类型选 “BPMN Process”从工具栏拖入 Start Event → User Task标注 “提交请假申请”→ Exclusive Gateway条件${days 3}→ User Task“部门经理审批”→ End Event右键 User Task → “Properties” → 在 “Assignee” 栏填manager对应 Flowable 的assignee属性点击右上角 “Save” → 弹窗输入 IDleaveProcess必须小写下划线不能含空格→ 确认。步骤 2部署流程定义点击顶部菜单 “File” → “Deploy” → 填写 Deployment Name如v1.0→ 点击 “Deploy”成功后跳转至http://127.0.0.1:8081/flow/#/deployments可见新部署项ID 为leaveProcess:1:xxx1为版本号。步骤 3启动流程实例并查询任务此时需调用 Flowable REST API 或 Java API 验证。推荐用curl快速测试# 启动流程实例需先获取登录 Token curl -X POST http://127.0.0.1:8081/api/runtime/process-instances \ -H Content-Type: application/json \ -H Authorization: Bearer fake-jwt-token-for-dev \ -d { processDefinitionKey: leaveProcess, variables: [ {name: days, value: 2}, {name: employeeName, value: 张三} ] }返回 JSON 中id即流程实例 ID。接着查待办任务curl http://127.0.0.1:8081/api/task/query \ -H Authorization: Bearer fake-jwt-token-for-dev \ -d {assignee:manager}响应中data数组应包含一条任务name为 “部门经理审批”processInstanceId与上一步一致。验证要点若task/query返回空数组检查assignee值是否与模型中设置完全一致区分大小写若流程实例未创建确认processDefinitionKey是否与 Modeler 中保存的 ID 完全匹配无前后空格。4. 生产就绪关键配置数据库表优化、历史清理与 Modeler 语言切换技巧Modeler 默认英文界面但国内项目常需中文支持Flowable 历史表ACT_HI_*若不清理会持续膨胀而ACT_GE_BYTEARRAY表存储 BPMN XML 和 PNG 图片单条记录可达数 MB。这些都不是“能跑就行”的范畴而是生产环境必须处理的细节。本项目虽未内置全部方案但提供了可直接复用的配置入口与代码片段。4.1 Modeler 界面语言切换修改 stencilset.json 与前端 i18n 文件Modeler 的语言由两部分组成节点标签文字由stencilset.json中title字段控制UI 控件文字如 “New Model”、“Deploy”由app-i18n.js中的messages对象定义。本项目src/main/resources/static/flow/i18n/zh-CN.json已预置中文翻译{ NEW_MODEL: 新建模型, DEPLOY: 部署, SAVE: 保存, START_EVENT: 开始事件, USER_TASK: 用户任务 }要启用中文需在app.js中加载该文件// flow/static/flow/app.js var locale zh-CN; $.getJSON(/flow/i18n/ locale .json, function(data) { messages data; });提示若i18n/zh-CN.json不存在Modeler 将回退至英文。可复制en-US.json并翻译重点覆盖messages下的键值对无需修改stencilset.json中的id字段如start-none只改title值即可。4.2 历史数据自动清理配置 HistoryCleanupJob 与保留策略Flowable 提供HistoryCleanupJob定时清理ACT_HI_*表避免磁盘耗尽。需在application.properties中启用# 启用历史清理作业 spring.flowable.history-clean-up-enabledtrue # 每 15 分钟执行一次 spring.flowable.history-cleanup-interval900000 # 保留最近 30 天的历史记录单位毫秒 spring.flowable.history-cleanup-period2592000000底层执行逻辑在HistoryCleanupJob类中其 SQL 语句为DELETE FROM ACT_HI_PROCINST WHERE END_TIME_ DATE_SUB(NOW(), INTERVAL 30 DAY); DELETE FROM ACT_HI_ACTINST WHERE END_TIME_ DATE_SUB(NOW(), INTERVAL 30 DAY); -- 其他 ACT_HI_* 表同理注意history-cleanup-period必须大于业务最长流程周期否则未结束流程的历史记录会被误删。若流程平均耗时 7 天建议设为6048000007 天的 2 倍以上。4.3 数据库表空间优化分离ACT_GE_BYTEARRAY存储与压缩策略ACT_GE_BYTEARRAY表默认存储 BPMN XML 和流程图 PNG单个 PNG 可达 2MB。当部署 100 个流程定义时该表体积轻易突破 200MB。优化方案有两种方案 A禁用 PNG 自动生成推荐在ProcessEngineConfig.class中关闭config.setCreateDiagramOnDeploy(false); // 部署时不生成 PNG config.setCreateImageOnFirstDeployment(false); // 首次部署也不生成此时ACT_GE_BYTEARRAY仅存 XML体积下降 90%。流程图可在 Modeler 中实时渲染无需持久化图片。方案 B外置存储适用于需审计截图的场景将ACT_GE_BYTEARRAY的BYTES_字段改为MEDIUMBLOBMySQL并在application.properties中配置# 启用外部存储需自行实现 ByteArrayDataManager spring.flowable.custom-byte-array-data-managercom.example.MyByteArrayDataManagerMyByteArrayDataManager需继承ByteArrayDataManager重写findByteArrayByDeploymentIdAndName()方法将字节流存至 MinIO 或本地文件系统。优化项默认值生产建议影响范围createDiagramOnDeploytruefalse减少ACT_GE_BYTEARRAY体积 90%historyLevelFULLAUDIT降低ACT_HI_DETAIL表写入频率asyncExecutorActivatetruefalse手动控制避免线程池争抢主线程资源最后一行技术动作执行mvn clean package后检查target/classes/static/flow/目录是否存在app.js和i18n/zh-CN.json确认路径层级与AppDispatcherServletConfiguration中的addResourceHandler配置完全一致——这是 Modeler 能正确加载中文界面的物理前提。本文还有配套的精品资源点击获取
尧图网站开发 