Spring Boot嵌入式集成Flowable Modeler：工作流引擎界面化落地实践

接到一个新需求要把后台管理系统的工作流引擎界面化业务人员能够直接在页面上拖拽画出BPMN流程而不是由开发人员先在IDE里画好再通过代码部署。项目技术栈还是熟悉的Spring Boot引擎侧用的是Flowable。这个场景如果没接触过很容易以为要单独部署一套Flowable UI的独立服务折腾各种端口和跨域结果和业务系统完全割裂。其实Flowable官方提供的Modeler模块完全可以嵌入到Spring Boot应用里让流程设计器成为系统的一个内嵌页面。本文就是基于我这次实际整合的完整经历把Spring Boot如何嵌入Flowable UI、如何将Modeler模块界面化这件事讲清楚包括版本选型、依赖组合、静态资源路由、REST API联动、认证打通以及后续排坑过程给正在做同类工作流项目的同学一个可落地的参考。1. 为什么要费劲把Flowable Modeler嵌进Spring Boot1.1 从代码画流程到界面画流程的关键转变很多项目中Flowable的流程定义一开始都是开发人员在Idea里装个插件或者用在线工具把BPMN画好生成一个XML文件放到项目资源目录里再通过流程引擎API去部署。这套流程说不上错但问题在于业务需求是经常变的。审批链多了一个节点、某个网关条件要调整、表单字段要重排这些改动如果都要开发人员介入光是来回沟通和打包发版就够折磨人的。流程建模如果挪到界面上业务人员或者系统管理员自己就能改整个流程生命周期才能转起来。这次顺畅实现的关键是Flowable官方本来就提供了一套名为Flowable UI的前端应用其中Modeler模块就是专门用来做流程建模和流程定义维护的。它提供了基于AngularJS的图形界面拖拽节点、配置监听器、定义网关分支这些都能在浏览器里完成。我们要做的事情简单说就是把这套UI从官方预置的部署形态中剥离出来作为Spring Boot应用内的一部分去托管。1.2 Modeler在Flowable UI全家桶里的角色Flowable UI在6.x版本里通常是一个可以独立启动的Web应用包含了多个模块模块核心作用是否有必要嵌入业务系统IDM用户身份管理、登录认证看情况通常需要替换成自己系统已有的用户体系ModelerBPMN模型设计器支持拖拽建模、编辑、保存本次嵌入的核心目标Admin引擎配置管理、定时任务、节点数据维护一般不用运维性质太强Task待办任务视图个人任务处理可以当作参考但多数业务系统有自己的一套任务中心在我这次项目里最关心的就是Modeler。它负责暴露三个核心能力第一流程图的在线绘制和编辑第二以JSON形式保存模型结构这个JSON是Flowable自己定义的stencilset格式第三将模型转换为BPMN XML并部署到流程引擎。嵌入之后用户不需要打开任何外部系统登录自己后台可以直接进入建模页面。1.3 直接嵌入与独立部署的路线对比最开始我也考虑过独立部署一套Flowable UI然后用nginx反代或者嵌入iframe。这个方案本身没有硬伤但实际一做就有几个麻烦一是运维上多了一个需要维护的Java Web进程占内存而且部署上线要多一份配置二是界面风格和统一登录很难融合iframe里的会话管理和业务系统的session要来回同步三是前端要调用建模后端的接口如果是跨域场景Cookie、Token传递都要额外设计。相比之下把Modeler模块嵌入到Spring Boot进程内部虽然前期整合代码多一点但后续使用体验是最顺畅的。所有建模能力变成同一个应用下的某个路径资源、接口、数据源都共享一套没有跨域问题没有多服务部署问题。页面上也能更方便地加自定义分类、按钮和自己的业务组件。2. 版本选型与依赖引入的前置准备2.1 Spring Boot 2.7搭配Flowable 6.7.2的实测组合版本是第一个要拍板的事情。我这次用的是Spring Boot 2.7.18加上Flowable 6.7.2。为什么要固定到这个组合Flowable 6.x官方对Spring Boot的兼容区间是2.x这一代从实际集成反馈来看2.6到2.7之间的Spring Boot配合Flowable 6.6以上版本最稳。Spring Boot 3.x配的是Flowable 7.x但是Flowable 7以后官方把UI模块的发布方式改了不再提供完整的war包和可嵌入的UI依赖Modeler能力被收拢到独立的Design Center产品线那种集成的路子跟本文说的不一样。如果你也是在新项目上做选型我的建议是不要盲目追新版本。Spring Boot 2.7虽然没有新特性冒头但它和Flowable 6.7.2的组合足够成熟网上的资料、踩坑案例也最丰富。真的出了奇怪问题大概率有人已经遇到过。2.2 核心Maven依赖应该怎么引引入依赖之前先明确一个概念Flowable的嵌入UI并不是一个单一starter就能拉起来的它需要前端资源、RESTController、公共工具类三部分搭配。我项目的pom里加入了这些关键的依赖dependency groupIdorg.flowable/groupId artifactIdflowable-spring-boot-starter-process/artifactId version6.7.2/version /dependency dependency groupIdorg.flowable/groupId artifactIdflowable-spring-boot-starter-rest/artifactId version6.7.2/version /dependency dependency groupIdorg.flowable/groupId artifactIdflowable-ui-modeler/artifactId version6.7.2/version /dependency dependency groupIdorg.flowable/groupId artifactIdflowable-ui-modeler-rest/artifactId version6.7.2/version /dependency dependency groupIdorg.flowable/groupId artifactIdflowable-ui-common/artifactId version6.7.2/version /dependency其中flowable-spring-boot-starter-process是流程引擎的核心负责RepositoryService、RuntimeService这些引擎服务flowable-spring-boot-starter-rest提供的是/process-api开头的REST接口让前端可以通过HTTP方式直接操作流程定义、部署流程flowable-ui-modeler提供建模器的前端静态资源和AngularJS界面flowable-ui-modeler-rest提供的是/app/rest开头的那套建模专用接口模型保存、读取、校验、转XML靠它flowable-ui-common则提供公共组件比如用户信息管理、应用配置。2.3 数据源与配置文件的隐藏要求Flowable引擎一旦启动就会自动创建大量ACT_开头的数据表这是引擎自己使用的包括流程实例、任务、流程定义等。而Flowable UI的Modeler模块还有另一组数据表主要保存设计器里的模型JSON数据、模型分类和模型历史版本信息这组表的名字大多以ACT_DE_开头。首次启动时如果database-schema-update设置正确引擎附近的表会自动建但Designer相关表能否自动创建取决于flowable-ui相关依赖里的初始化逻辑。实际项目中更稳妥的做法是在第一次启动前先手动执行官方提供的designer建表SQL。这些SQL文件一般可以在flowable-ui安装包解压后的sql目录下找到按照数据库类型选择对应脚本执行里面的Designer部分即可。我的配置如下spring: datasource: url: jdbc:mysql://localhost:3306/flowable_demo?useUnicodetruecharacterEncodingutf8nullCatalogMeansCurrenttrue username: root password: yourpassword driver-class-name: com.mysql.cj.jdbc.Driver flowable: database-schema-update: true async-executor-activate: false rest: app: authentication-mode: verify-privilege这里有两个关键配置要说明。nullCatalogMeansCurrenttrue这个参数在MySQL下经常被忽略但它直接影响Flowable初始化建表时的表名扫描如果漏了偶尔会出现表已经存在但引擎认为不存在的错乱。async-executor-activate我关掉了是因为这个项目里暂时不想让流程引擎在后台自动跑异步执行器保持单一进程内简单可控。2.4 开始写代码前先规划好路径在动手写代码前还有一件事要先想明白访问路径规划。官方Flowable UI是通过/modeler这个根路径来访问建模页面的静态资源通常分散在/modeler、/scripts、/idm等路径下。嵌入到Spring Boot后这些路径会占用你的应用上下文路径。如果你的业务系统已经有了/modeler这个路径或者把context-path设置得比较复杂就得先调整前端资源的引用路径。我的项目里保持默认的context-path也就是说建模页面就是http://localhost:8080/modeler业务接口放在/api下两类路径互不干扰这是最简单的方式。3. 界面资源与后端API的整合实战3.1 前端静态资源从哪来怎么放进去Flowable UI的静态资源说到底是官方war包里的那些文件。最直接的办法是下载对应版本的flowable-ui发布包解压后把目录整理进Spring Boot项目的src/main/resources/static下。具体拿我用的6.7.2来说解压后的webapp目录下会看到modeler、idm、scripts、views等目录其中modeler目录里放着模型设计器主页面index.html以及一大串AngularJS的组件代码而scripts和views是多个UI模块共享的前端资源不能只拷modeler目录需要一并放进去。拷贝的时候注意不要整包把所有UI模块都拷进来如果不需要Admin和Task页面就只保留modeler、scripts、views、idm这几个公共资源这样静态资源目录干净很多后续也容易维护。3.2 让Spring Boot正确接管这些静态页面Spring Boot对classpath:/static/下的内容默认当成静态资源处理。我把资源放到位后正常情况下访问http://localhost:8080/modeler/应该能直接返回页面。但这里的坑在于Modeler的前端路由是AngularJS的hash路由也就是说真正加载的页面地址是/modeler/index.html#/这样的长格式静态资源映射必须让/modeler/**能落到static/modeler目录下。如果你还保留了Spring Security等框架千万注意放行策略。我在项目里新增了一个配置类专门放开对UI资源、建模API的路由Configuration public class FlowableUiSecurityConfig extends WebSecurityConfigurerAdapter { Override protected void configure(HttpSecurity http) throws Exception { http .csrf().disable() .authorizeRequests() .antMatchers( /modeler/**, /scripts/**, /views/**, /app/rest/**, /process-api/**, /idm/** ).permitAll() .anyRequest().authenticated(); } }这里多说一句开发环境为了调试方便直接全部放行没有大问题但生产环境必须有网关或前置拦截器把认证补上否则建模接口裸奔在公网上是重大安全隐患。3.3 APP REST接口如何装配到Spring Boot容器中Modeler前端在页面上操作时发起的所有HTTP请求都是/app/rest/开头的这些请求的Controller并不存在于flowable-spring-boot-starter-process里而是在flowable-ui-modeler-rest这个模块中。具体拿保存模型这个动作来说前端会把模型JSON和SVG信息提交到/app/rest/model这个接口再由底层Service落到ACT_DE_MODEL表。但这种Controller不是自动注册到Spring Boot的。如果你的主启动类只扫描自己的包那flowable-ui包里的Controller不会被扫描到。这时候有两种处理办法一种是在启动类上直接加ComponentScan(basePackages {com.yourproject, org.flowable.ui})把整个Flowable UI相关的包都纳入扫描范围另一种是用Import显式引入Modeler模块里的配置类。不同小版本Configuration类的位置略有差异我这边是直接加大范围扫描解决的注意扫描范围变宽后要防止包之间出现Bean冲突如果启动时报了同名字的Filter或Service冲突排查优先级最高。3.4 启动验证的完整步骤依赖和配置都就位后启动Spring Boot应用我按这几步做了验证第一步启动日志里出现了Flowable的初始化信息同时看到ACT_DE_MODEL相关表存在说明Designer的数据表没有缺失。第二步在浏览器访问http://localhost:8080/modeler/页面能渲染出Flowable Modeler的登录界面虽然此时认证还没整合但至少说明静态资源路径是对的。第三步打开开发者工具看Network面板手动触发一次模型列表刷新确认/app/rest/models这样的请求有响应不要急着看界面效果先确认接口层通了。如果你在第一步就发现表缺失不要犹豫把数据库里ACT_DE开头的表手动建一遍再启动。我在初期的环境里吃过这个亏界面框架加载出来了但一登录就报数据库表不存在查了半小时才发现是designer脚本没有单独执行。4. 认证、路径与权限的打通方案4.1 前端认证链路的实际模样Modeler界面默认的认证逻辑是依赖Flowable IDM模块的也就是说页面第一眼看到的是一个登录框用户通过/idm接口登录前端拿到登录用户信息后在本地缓存后续调用/app/rest接口时通过请求头把用户身份带过去。当你把它嵌进自己的Spring Boot系统时这套逻辑大概率是要改造的。有两种改造方向第一种是把Flowable IDM的用户表和业务系统的用户表做映射登录后手动签发Flowable的Token这种方式能保留官方前端的所有行为但属于啃IDM这块硬骨头第二种是把Modeler当成一个受限的内部工具页面跳过官方登录页直接让已经登录业务系统的用户进入建模器身份信息由后端统一注入。4.2 我最终采用的统一登录方案项目里已经有一套成熟的登录认证体系再让用户额外输入一次Flowable的账号密码体验上完全不可接受。所以我选的是第二种方案核心思路是既然前端的所有请求最终都会打到后端的/app/rest接口那我就在后端加一个过滤器把所有进入/app/rest的请求拦截下来从当前业务登录会话中解析出用户信息然后写入Flowable的认证上下文。Flowable本身提供了org.flowable.common.engine.impl.identity.Authentication这个类可以手动设置当前线程里的认证用户。我在项目里设计了一个过滤器Component public class FlowableUserContextFilter extends OncePerRequestFilter { Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ServletException, IOException { // 从业务系统的session或token中解析当前登录用户 String userId SecurityUtils.getCurrentUserId(); if (userId ! null) { Authentication.setAuthenticatedUserId(userId); } try { chain.doFilter(request, response); } finally { Authentication.setAuthenticatedUserId(null); } } }这个改造的关键在于Flowable在创建流程、记录操作人、权限判断时都是从Authentication.getAuthenticatedUserId()取当前用户的。很多项目集成完UI后发现建模记录里操作人一直为空或者任务分配历史看不到发起人基本都是因为少了这一步。4.3 放行路径的边界与安全底线虽然我在前面的安全配置里临时放行了一大批路径但必须强调这只适合内部管理系统或开发环境。生产环境如果应用暴露在公网至少要保证两点一是外网访问通过网关层强制校验登录态所有/app/rest请求在进入应用前已经确定用户身份二是Spring Security放行路径要精细化最好只在认证过滤器通过后才放行而不是无条件permitAll。如果你所在的团队安全要求严格还有一个折中方案保留Flowable自身对/app/rest接口的BaseAuth校验同时在业务系统登录成功后把用户名和密码加密信息注入到前端发起请求的拦截器中每次请求自动带上Authorization头。这样后端就不用写自定义过滤器了也保留了Flowable自身的权限校验逻辑。但这个方案要求前端改造多一些并且用户密码信息的安全存储要额外处理。4.4 自定义分类和用户体系的后续接入让Modeler跑起来只是第一步真正融入业务系统还需要把官方UI里存放的默认用户体系替换掉并让自己的流程分类体系在建模器里展示出来。建模器左侧的分类列表来自/app/rest/model接口的一个参数后端返回的模型分类数据可以从Flowable的默认分类表读取也可以改成从业务系统的字典表来。我的做法比较取巧在后端写了一个Controller适配层把业务系统的分类字典转换成前端需要的JSON结构前端不用改一行代码就能看到自己系统的分类。这样做看似绕了一下但好处是不用动官方前端的AngularJS源码后续Flowable版本升级也能平滑过渡。5. 集成后典型问题排查与经验总结5.1 页面白屏Index加载了但JS全部打不开首次部署后访问/modeler/页面确实出来了但过一会儿白屏控制台一堆404报错。检查发现modeler/index.html里引用静态资源的路径是绝对路径/scripts/xxx.js而Spring Boot静态资源默认映射根是/static/我一开始把scripts目录放到了static/modeler/scripts下面导致根路径访问不到。解决办法很简单把scripts、views、idm这些共享资源保持在与官方war包相同的路径层级也就是static/scripts、static/views、static/idm而不是放进static/modeler里面。这样所有相对根路径的引用都不会404。5.2 模型保存失败后端500报错建模页面能打开也能画节点但一保存就报错。我这边遇到的报错原因是数据库字段长度不够Flowable的Model设计器在保存JSON模型时会把很大一段JSON字符串写到ACT_DE_MODEL表的model_editor_json字段里。默认建表脚本里这个字段是长文本类型但某些数据库方言下如果初始化脚本没有正确执行字段类型可能只是VARCHAR(255)模型稍大一点就超长报错。这种问题在正式环境很难一眼看出来因为界面上的提示只是保存失败。排查思路是打开后端异常日志如果看到Data truncation或Value too long for column基本就是这个问题。解决起来也直接把ACT_DE_MODEL表里模型相关的大字段改成LONGTEXT或对应的文本类型即可。5.3 REST接口与业务接口产生路径冲突我们的业务接口统一放在/api前缀下所以/app/rest和/process-api没有直接冲突。但如果你项目里本来就有/app/**之类的路由就要小心路径被业务Controller吃掉。最好的做法是给Flowable相关接口单独加一层显式的前缀我这边的做法是改写spring.mvc.pathmatch的兼容策略同时在启动类上用server.servlet.context-path保持留空确保Flowable UI的原始路径不被改变。如果你实在需要改变路径前缀比如必须在/workflow下面访问那么不只是改后端路由前端AngularJS工程里所有REST请求地址也要同步替换那属于前端二次开发的内容改动量会明显上升。我的建议是尽量不动官方路径让Modeler的访问路径独立存在。5.4 任务中心与流程定义不同步的经验模型设计器里的保存和部署和实际流程引擎里的流程定义之间还有一段距离。Modeler里保存的是建模JSON只有点了部署按钮后端才会把JSON转成BPMN XML再丢给流程引擎发布成真正的流程定义。我在集成过程中发现如果用户只想保存草稿那流程引擎里什么变化都没有而一旦点了部署立刻就能在自己的任务中心发起新流程。这个动作的衔接是Modeler界面化交付中最重要的一环业务方往往理解不了Why我保存了流程还不能用所以交付时一定要在操作文档和系统提示里明确区分保存草稿和部署发布。另外一个场景是模型版本管理。Flowable会自动为同一个key的模型记录历史版本每次部署都会生成新的流程定义版本这个机制是开箱即用的不需要额外开发但要在界面上给用户做好提示避免他们以为流程定义被覆盖丢失了。5.5 集成后维护成本小结说实话把Modeler嵌入Spring Boot这件事第一次跑通大概需要两天左右时间但跑通之后维护成本并不高主要工作量集中在三个地方一是Flowable版本升级时前端资源和后端接口要一起升级不能只换引擎jar包二是业务系统的用户体系改动时UI内操作的当前用户信息也要跟着适配三是数据库备份和恢复时不能只备份ACT_RU、ACT_HI这些工作流运行表ACT_DE_开头的设计器表也要纳入备份范围否则模型设计数据会丢。我经历过一次测试环境数据库恢复只导了引擎相关表结果Modeler界面能打开但所有模型列表都是空的业务方差点以为建模功能彻底坏了。后来把ACT_DE_MODEL和ACT_DE_MODEL_RELATION等表手动补建后数据才回来。这个坑强烈建议大家放进自己的运维手册里。