JeecgBoot 集成 Flowable 流程引擎实战：从依赖接入到在线画流程、挂表单、跑通审批

JeecgBoot 集成 Flowable 流程引擎实战：从依赖接入到在线画流程、挂表单、跑通审批

【免费下载链接】jeecg-boot【低代码v2.0，一句话即可生成整个系统】企业级AI低代码平台，一键生成前后端代码甚至整个系统。 AI Skills 一句话画流程、设计表单、生成报表、大屏。内置 AI应用平台涵盖：AI聊天、知识库、流程编排、MCP插件等，兼容主流大模型。引领AI低代码「Skills 生成 → 在线配置 → 代码生成 → 手工合并->AI修改」开发模式，解决 Java 项目 90% 重复工作，提高效率又不失灵活。项目地址: https://gitcode.com/GitHub_Trending/je/jeecg-boot

很多团队的审批流现状是这样的：邮件发申请、Excel 转发签字、群里@领导催进度——慢、乱，还没法追溯。把这类"谁在什么时候批了什么"的逻辑写死在业务代码里，每加一个审批环节都要改代码发版。JeecgBoot 与 Flowable 流程引擎的集成就是为了解决这个问题：Flowable 是一个开源 BPM 引擎，你可以把它理解成专门跑审批流程的后台服务；而 JeecgBoot 低代码平台则把它包装成"在线画流程 + 表单挂接"的可视化能力，让流程定义和业务代码解耦。本文带你走完一条完整主线：接入引擎 → 打通登录认证 → 画流程 → 挂表单 → 跑起来验证，最后附上踩坑清单。

一、三步让 Flowable 引擎在 JeecgBoot 里跑起来

如果还没拉过代码，先 clone 一份项目：

git clone https://gitcode.com/GitHub_Trending/je/jeecg-boot

1. 引入依赖：一个 starter 加几个 UI 包

引擎接入的核心是flowable-spring-boot-starter，它会帮你把 Spring 容器和流程引擎的启动过程绑在一起。JeecgBoot 推荐锁定 6.7.2 版本，与平台整体的 Spring Boot 版本兼容性最稳。设计器相关依赖按需添加即可，不用全上：

<properties> <flowable.version>6.7.2</flowable.version> </properties> <dependencies> <dependency> <groupId>org.flowable</groupId> <artifactId>flowable-spring-boot-starter</artifactId> <version>${flowable.version}</version> </dependency> <!-- 在线流程设计器 REST API，不需要可视化设计可去掉 --> <dependency> <groupId>org.flowable</groupId> <artifactId>flowable-ui-modeler-rest</artifactId> <version>${flowable.version}</version> </dependency> </dependencies>

任务管理（flowable-ui-task-conf）、管理控制台（flowable-ui-admin-conf）、身份管理（flowable-ui-idm-conf）这几个包同理，用到哪个加哪个。

2. 数据库配置：表会自动建，别手动导

Flowable 启动时会按database-schema-update策略自动创建和升级自己的表结构，所以这一步基本只是确认两件事：

• 表会出现在哪个库：默认跟随主数据源；流程数据量大的项目可以给它单独配一个库（见文末扩展）；
• 流程文件从哪加载：classpath*:/processes/下的.bpmn文件会在启动时自动部署。

flowable: async-executor-activate: true # 开启异步执行器，定时器/异步任务靠它 database-schema-update: true # 允许启动时自动更新表结构 process-definition-location-prefix: classpath*:/processes/ process-definition-location-suffixes: "**.bpmn20.xml, **.bpmn"

JeecgBoot 侧的基础库脚本在 db/jeecgboot-mysql-5.7.sql，先导入它再启动，Flyway 会处理后续增量迁移。

3. 验证引擎活着

启动后注入RepositoryService能拿到对象、数据库里出现ACT_开头的表（ACT_RE_*存流程定义、ACT_RU_*存运行时任务），说明引擎已经就绪。

二、打通登录：让 Flowable 认出 Shiro 体系里的用户

这一步最容易翻车。Flowable 自带一套 Spring Security 登录（账号密码都是默认值），而 JeecgBoot 用的是 Shiro + JWT，两边身份不通的话，流程里记录的"发起人"永远是错的，或者设计器页面弹出一个孤立的登录框。

1. 关掉 Flowable 的独立登录

用一个HttpSecurity配置，把设计器和管理页面直接放行，认证交给 JeecgBoot 自己的体系：

@Configuration @Order(SecurityConstants.FORM_LOGIN_SECURITY_ORDER - 1) public static class FormLoginWebSecurityConfigurerAdapter extends WebSecurityConfigurerAdapter { @Override protected void configure(HttpSecurity http) throws Exception { http.headers().frameOptions().disable(); http.csrf().disable() .authorizeRequests() .antMatchers("/modeler/**", "/flowable/**") .permitAll(); } }

2. 把当前登录用户注入 Flowable 上下文

Flowable 通过Authentication上下文里的用户 ID 记录流程发起人、办理人。我们实现一个轻量适配器，把 Shiro 会话里的当前用户 ID 喂给它，并在应用启动完成后注册一次：

@Component public class FlowableStartedListener implements ApplicationListener<ContextRefreshedEvent> { @Override public void onApplicationEvent(ContextRefreshedEvent event) { Authentication.setAuthenticationContext(new AuthenticationContext() { @Override public String getAuthenticatedUserId() { // 返回 Shiro 会话中的当前用户 ID return SecurityUtils.getCurrentUserId(); } @Override public Principal getPrincipal() { return null; } @Override public void setPrincipal(Principal principal) { } }); } }

3. 顺手解决流程图中文变方块

流程图中节点文字、注释用的字体如果不配置，部分 Linux 服务器会渲染成方块。在引擎配置类里指定中文字体即可：

@Configuration public class FlowableConfig implements EngineConfigurationConfigurer<SpringProcessEngineConfiguration> { @Override public void configure(SpringProcessEngineConfiguration cfg) { cfg.setActivityFontName("宋体"); cfg.setLabelFontName("宋体"); cfg.setAnnotationFontName("宋体"); } }

💡 前提：运行环境里要有对应的中文字体（Docker 镜像里记得fonts-noto-cjk）。

三、用可视化设计器画出审批流程

登录打通后，打开/flowable-ui（或前端对应的流程设计入口），你会看到一个基于 BPMN 2.0 的拖拽设计器。整体分工大致是下面这样：

一张图看清设计器各部分如何汇总成一份 BPMN 流程定义。

画一个"请假审批"就是三件事：

1. 拖节点：开始 → 提交申请（用户任务）→ 网关（按假期天数走不同分支）→ 部门主管审批 → 结束；
2. 配处理人：用户任务节点上指定候选人或候选组（比如dept_manager角色），条件分支上写 EL 表达式，如${days > 3}；
3. 保存部署：设计器提交后生成 BPMN XML 并部署进ACT_RE_PROCDEF，同 key 再次部署自动升版本号，不影响在跑的旧实例。

服务任务节点可以挂 HTTP 调用、邮件发送这类自动化动作，不需要人工介入的环节都往这放，流程会更轻。

四、把审批表单挂到流程节点上

流程画完，下一个问题：每个节点上的那张表单从哪来？JeecgBoot 的思路是流程管流转，表单管数据，两者通过 key 关联，支持三种挂接模式：

绝大多数场景用静态表单就够：在开始节点绑定表单 key（"必须配置"，因为流程启动的数据从这来）；用户任务节点上的表单可选，审批环节通常只需要"同意/驳回 + 意见"，可以直接用引擎内置任务表单；服务任务和结束节点不需要表单。

1. 表单数据怎么在节点之间流转

核心机制是流程变量：表单提交时调用startProcessInstanceByKey并setVariables，数据就进了引擎；后面每个节点通过变量取值，审批完成时把新字段写回。整条链路是这样的：

表单数据借助流程变量在节点间共享，业务代码全程不感知。

2. 字段级控制怎么做

审批场景常见的两个需求：

• 条件显隐：表单配置里支持表达式，例如"请假类型=病假"时才显示"医疗证明"上传项；
• 字段权限：不同节点对不同字段给只读/可编辑权。做法是在任务表单渲染时，按当前 taskId 查一份字段权限配置，把不可写字段置灰——表单数据进引擎前过一遍过滤，避免越权修改。

表单模板本身也建议做版本管理：流程定义引用的是表单 key 而不是死链接，表单迭代升级时通过版本号校验兼容性，老实例继续用旧版。

五、跑一个完整流程并确认它通了

部署后别急着验收，按这个顺序自检一遍：

1. 表验证：ACT_RE_PROCDEF里能查到你的流程定义，版本号从 1 递增；
2. API 验证：调用任务查询接口，流程停在正确的用户任务上，候选人与你配置的一致；
3. 身份验证：任务assignee/candidate字段是 JeecgBoot 体系里的真实用户 ID，而不是demo或空值；
4. 变量验证：审批完成后再查ACT_RU_VARIABLE，表单数据已随节点流转。

回归测试里放一个最小用例，保证以后升级引擎版本时能第一时间发现问题：

@SpringBootTest class FlowableIntegrationTest { @Autowired private RepositoryService repositoryService; @Test void engineShouldBeReady() { assertNotNull(repositoryService); // 能按 key 查到已部署的流程定义即视为集成正常 assertNotNull(repositoryService .createProcessDefinitionQuery() .processDefinitionKey("leave") .singleResult()); } }

✅ 四项全过，一个完整的审批闭环就算跑通了。

六、常见踩坑点与可选扩展

⚠️ 这几个坑基本每个项目都会碰到：

• 版本混用：Flowable 各包版本必须严格一致（统一${flowable.version}），starter 是 6.7.2 而 modeler 是 6.5.0 这类混搭会直接启动报错；
• 数据源隔离：想给流程单独建库时，在FlowableConfig里显式setJdbcUrl/setJdbcDriver/setJdbcUsername/setJdbcPassword，或单独建一个带@Qualifier("flowableDataSource")的 DataSource + 事务管理器；别忘了 Flowable UI 的 Liquibase 表要加ACT_DE_前缀避免与主库迁移记录冲突；
• 多租户：flowable.common.app下的租户/管理员配置只在启用 UI 套件时需要，纯引擎场景不用配；
• 历史级别：默认audit够用，若不需要全量变量历史可用activity降低表膨胀速度，并配cleanup定期清理。

扩展方向上，如果你的模块划分参考 CLAUDE.md 中的架构说明，BPM 能力通常独立成jeecg-boot-module-bpm-flowable这类模块，通过 jeecg-boot-module/ 下的模块机制挂载，主应用按需引入。再往上可以叠加：服务任务对接消息/邮件通道、任务中心按候选组做待办聚合、流程与权限菜单联动（把"我的审批"做成系统内置菜单）。

总结：接入 Flowable 真正要做的只有四件事——引依赖、打通用户身份、画流程、挂表单。依赖和建表交给 starter 自动化，身份打通是唯一必须手写的核心代码（约 30 行），剩下的工作都在设计器和表单配置里完成。流程引擎与业务表单松耦合之后，改审批环节不再改代码，这正是引入 Flowable 的全部价值。

【免费下载链接】jeecg-boot【低代码v2.0，一句话即可生成整个系统】企业级AI低代码平台，一键生成前后端代码甚至整个系统。 AI Skills 一句话画流程、设计表单、生成报表、大屏。内置 AI应用平台涵盖：AI聊天、知识库、流程编排、MCP插件等，兼容主流大模型。引领AI低代码「Skills 生成 → 在线配置 → 代码生成 → 手工合并->AI修改」开发模式，解决 Java 项目 90% 重复工作，提高效率又不失灵活。项目地址: https://gitcode.com/GitHub_Trending/je/jeecg-boot