Spring Boot集成Flowable Modeler：把流程画布嵌入后台的完整实践

最近在整理一套审批流后台，核心需求就是把流程建模这件事从开发手里交还给业务人员。选型的时候没纠结太久，引擎直接用Flowable，但它自带的Modeler是独立的一套UI，项目里不可能让用户跳转到另一个端口去画流程图。最终做下来的方案就是：Spring Boot后端承载Flowable引擎，把Modeler模块的界面化能力完整嵌入到现有后台里，用户登录一次，点进菜单就能直接画BPMN图、保存、部署。这篇文章就把整个落地过程、选型思路和踩过的坑完整记录下来，给准备做同类集成的朋友一个参考。

如果你只是想看看Flowable长什么样，那直接用官方一键启动包就行；但如果你要把Modeler真正融进自己的系统，需要解决的不只是静态资源路径，还有前后端交互、鉴权冲突、模型存取、部署链路这一长串问题。下文会按我实操的先后顺序展开，内容偏向能直接照做的干货。

1. 嵌入前先想明白：你要的到底是界面还是接口

1.1 直接嵌入官方UI的三个典型痛点

很多团队在做工作流改造时都会遇到类似的场景：流程引擎已经跑起来了，但流程图还是开发手工画好再部署；或者用了Flowable官方UI，却发现业务人员要在自己的管理系统和建模工具之间来回切换。

直接把官方Modeler整体嵌进来，能解决体验割裂的问题，但也会带来三个绕不开的痛点。第一是权限体系冲突，Flowable官方的Modeler后台自带IDM用户管理和Spring Security配置，和自家系统的登录态往往互不相认，不做处理的话要么登录失效，要么你能直接绕过自家安全策略访问到建模器。第二是路由和资源加载，Modeler前端有一套自己的路由规则和静态资源配置，盲目塞进Spring Boot的static目录会出现页面空白、样式丢失、接口404之类的连锁问题。第三是模型存储链路，官方UI保存模型时同时写编辑器JSON和BPMN XML两份数据，如果你只想留一份，后续部署流程定义就会发现数据对不上。

这些问题不解决，界面嵌进去了也只是一个花架子，真正用起来处处是坑。

1.2 两条技术路线：全家桶继承与轻量自建Rest

我在选型阶段对比过两条路线。第一条是直接引入flowable-ui-modeler相关依赖，让官方REST接口跟着你的Spring Boot工程一起跑，前端也用官方Vue工程，属于“全家桶”思路。这条路的好处是接口齐全，保存、导出、部署、历史模型样样都有；坏处也明显，它自带的Security配置会跟你项目里的安全框架打架，很多时候你不得不用各种排除配置去压制它，而且官方接口的路径、参数和返回结构是固定的，你想在保存模型时顺手塞业务字段，改造起来很别扭。

第二条路线是轻量自建Rest接口。只引入flowable-spring-boot-starter流程引擎，Modeler界面前端用自己的后端接口对接，官方那套UI只当做一个“画图页面”来用。这条路的优点是完全掌控，鉴权跟着自己系统走，模型列表想展示哪些字段随意控制，部署动作前还能插入自动检查；缺点是需要自己补齐接口，工作量大一些，但每个接口都很直白。

我最终选了第二条。原因是项目里本来就有统一登录和菜单权限，为了一个画图工具去迁就官方全家桶，后续维护成本太高。自建Rest接口虽然多写了几个Controller，但对整个团队来说结构更清晰。

1.3 最终架构拆解

落地后的架构其实只有四块：Spring Boot承载的Flowable引擎、一组自建的模型管理Rest接口、官方Modeler前端构建产物、以及两者之间的静态资源映射和鉴权拦截器。

用户从后台菜单点进建模器后，浏览器加载Modeler前端页面，页面通过自己配置的API地址请求后端模型管理接口。模型列表、编辑器JSON、BPMN XML、部署操作全部走这一组接口。前端只负责画图和编辑，后端负责存储和转换。我额外留了一个转换动作在保存模型时同时生成BPMN XML，部署流程时直接读XML，绕开了官方UI那份双格式存储的复杂度。

这种结构的扩展性也不错。后续如果要把表单设计器也嵌进来，或者给模型列表加搜索、分组、版本对比，只需要在自建接口和前端菜单上扩展，完全不受官方UI的约束。

2. 动手前必须定死的版本与基础配置

2.1 Flowable、Spring Boot、JDK的版本矩阵

版本这件事必须放在最前面说，不然你会被各种类路径报错折磨到怀疑人生。Flowable社区版常见的几个版本段对运行环境要求差异很大。

我这次用的是6.7.x搭配Spring Boot 2.7，主要是考虑到项目里其它依赖都还留在JDK8生态，不想为了一个建模器把整个技术栈推到17。如果你是从零开始的新项目，并且团队熟悉JDK17，那直接上7.x也没有问题。但要注意，Modeler相关前端源码在不同大版本之间差异不小，不要拿6.x的构建产物去配7.x的后端接口，两者很多请求参数已经不兼容。

2.2 数据库准备与自动建表策略

Flowable引擎对数据库的依赖很重，模型数据、流程定义、部署数据都会落库。我这里用的MySQL，字符集一定要明确指定utf8mb4，否则模型描述里只要出现中文，保存时就有可能出现乱码或者直接报索引超长。

DataSource配置里加上useUnicode=true、characterEncoding=utf8mb4、serverTimezone=Asia/Shanghai这三项，基本能规避大部分编码和时区问题。Flowable首次启动时通过database-schema-update配置自动建表，默认值true表示如果表不存在就自动创建，方便但不适合生产环境反复重启。项目稳定后可以改成false或者用专门的迁移脚本管理表结构，避免版本升级时自动改表引起意外。

idm.enabled要视情况关闭。如果你完全不需要Flowable自己的用户体系，把flowable.idm.enabled设成false是最干净的，能减少很多默认表的生成和权限干扰。但要注意，官方UI工程里如果还有登录页逻辑，关闭IDM后你需要确保前端不会跳转到它自己的登录地址。

2.3 流程引擎核心配置速记

除了数据库和IDM，异步执行器也要提前决定。工作流里很多场景会用到异步任务，但如果你只是先做建模和部署验证，异步执行器可以先关掉。配置成false能让启动日志更清爽，减少后台异步线程对测试环境的干扰。

页面表单、待办任务这些功能用不用，决定了你后续引入哪些Flowable模块。我的做法是内核统一引入flowable-spring-boot-starter，覆盖引擎最核心能力，等需要任务服务、表单服务时再按需补依赖。不要一开始就复制一整份官方starter全家桶，依赖之间的版本冲突会摊到你面前一堆莫名其妙的运行时异常。

3. 后端落地：把Modeler需要的接口一个个补齐

3.1 模型增删改查是地基

自建模型管理接口，本质是把Flowable的RepositoryService能力包一层HTTP。先做一个模型查询接口，返回模型ID、名称、Key、版本、创建时间和最后修改时间，前端模型列表就展示这些字段。

@GetMapping("/api/flowable/model/list") public Map<String, Object> listModel(@RequestParam(defaultValue = "1") int page, @RequestParam(defaultValue = "10") int size) { List<Model> models = repositoryService.createModelQuery() .orderByModelCreateTime().desc() .listPage((page - 1) * size, size); long count = repositoryService.createModelQuery().count(); List<Map<String, Object>> rows = models.stream().map(model -> { Map<String, Object> row = new HashMap<>(); row.put("id", model.getId()); row.put("key", model.getKey()); row.put("name", model.getName()); row.put("version", model.getVersion()); row.put("createTime", model.getCreateTime()); row.put("deploymentId", model.getDeploymentId()); return row; }).collect(Collectors.toList()); Map<String, Object> result = new HashMap<>(); result.put("data", rows); result.put("count", count); return result; }

创建模型时除了在ACT_RE_MODEL表插入一条记录，还要初始化一个空白的编辑器JSON，让前端打开画布时能拿到一个可编辑的初始结构。官方Modeler的编辑器JSON有一套固定格式，包含stencilset、bounds、childShapes等节点。我在创建接口里先构造一个最小的JSON体，写入模型编辑器源，这样前端拿到后能正常初始化画布。

3.2 编辑器JSON与BPMN XML的双格式保存

这是整个集成中最关键的一个环节。Modeler前端画完图保存时，交给你的是一个Flowable编辑器专用的JSON结构，它跟标准BPMN XML不是一回事。如果你只把这个JSON存起来，后续部署、解析流程定义时引擎是认不出的。所以保存动作必须做一次格式转换，把JSON转成BPMN XML，两份数据都落库。

@PostMapping("/api/flowable/model/save") public void saveModel(@RequestBody SaveModelParam param) { Model model = repositoryService.getModel(param.getModelId()); byte[] jsonBytes = param.getEditorJson().getBytes(StandardCharsets.UTF_8); // 编辑器JSON转BPMN Model，再转成XML ObjectNode jsonNode = (ObjectNode) objectMapper.readTree(param.getEditorJson()); BpmnModel bpmnModel = new BpmnJsonConverter().convertToBpmnModel(jsonNode); byte[] xmlBytes = new BpmnXMLConverter().convertToXML(bpmnModel, "UTF-8"); // 编辑器JSON用于再次进建模器编辑 repositoryService.addModelEditorSource(model.getId(), jsonBytes); // 标准BPMN XML用于部署和预览 repositoryService.addModelEditorSourceExtra(model.getId(), xmlBytes); model.setName(param.getName()); repositoryService.saveModel(model); }

转换这一步要依赖flowable-bpmn-converter的BpmnJsonConverter和BpmnXMLConverter，使用的时候记得把版本跟flowable核心依赖保持一致，避免遇到方法签名不兼容。实测下来，前端给的JSON结构偶尔会有多余的空节点或者属性类型不标准，转换前最好让前端先用官方Modeler的校验逻辑过滤一遍，否则后端会抛Jackson解析异常。

还有一点要提醒：保存模型时在转换成功之后再写库。如果出现异常，说明这次编辑内容有问题，不要覆盖掉上一份正常数据。我在这块吃过亏，后来改成先转换校验、通过后再写入，模型数据才稳定下来。

3.3 导出BPMN XML与一键部署流程

导出接口很简单，直接读模型额外源即可。但有些旧数据是只有JSON没有XML的，导出的时候要做一层兜底：读不到XML就现场从JSON转一份，保证下游拿到的永远是标准BPMN文件。

部署接口是业务价值最直观的落点。开发时代部署流程要手动敲命令，模型界面化之后业务人员画完图点一个部署按钮就完成。部署代码就是把模型额外源里的XML构造成一个String资源，提交给部署构建器：

@PostMapping("/api/flowable/model/deploy/{modelId}") public Map<String, Object> deploy(@PathVariable String modelId) { Model model = repositoryService.getModel(modelId); byte[] xmlBytes = repositoryService.getModelEditorSourceExtra(modelId); if (xmlBytes == null) { throw new IllegalArgumentException("当前模型缺少BPMN XML，请先保存模型"); } Deployment deployment = repositoryService.createDeployment() .name(model.getName()) .key(model.getKey()) .addString(model.getKey() + ".bpmn20.xml", new String(xmlBytes, StandardCharsets.UTF_8)) .deploy(); model.setDeploymentId(deployment.getId()); repositoryService.saveModel(model); ProcessDefinition definition = repositoryService.createProcessDefinitionQuery() .deploymentId(deployment.getId()) .singleResult(); Map<String, Object> result = new HashMap<>(); result.put("deploymentId", deployment.getId()); result.put("processDefinitionId", definition.getId()); result.put("processDefinitionKey", definition.getKey()); return result; }

部署之后及时把deploymentId回写到模型记录上，这个字段对用户很有用。界面上的模型列表可以直接显示“已部署”状态，点进去还能看到当前流程定义ID，方便和后续实例排查关联起来。

3.4 统一鉴权与路径设计

自建接口的路径我统一放在/api/flowable/model下面，鉴权由项目里已有的拦截器处理。这里是嵌入官方UI最容易翻车的地方，因为很多开发图省事，把官方的Rest接口直接放进工程，结果官方自带的安全过滤器把自家登录态拦了。

我的做法是在项目里加一个简单的HandlerInterceptor，校验前端传来的token或者登录会话，然后只把/api/flowable/**和Modeler静态资源路径放行给这个拦截器。这样既保证了画图页面可以正常打开，又不会让未登录用户直接访问模型接口。

@Component public class ModelerAuthInterceptor implements HandlerInterceptor { @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { String token = request.getHeader("X-Auth-Token"); if (StrUtil.isBlank(token) || !tokenValidator.check(token)) { response.setStatus(HttpStatus.UNAUTHORIZED.value()); return false; } return true; } }

前端每次发请求时统一在axios拦截器里把用户token塞进请求头，后端这个拦截器只认这个token，登录体系完全掌握在自己手里，不会出现官方UI自己弹出来一套登录框的尴尬。

4. 前端落地：让画图板真正出现在后台页面里

4.1 Modeler前端资源怎么来

前端部分我用的是Flowable官方Modeler的Vue工程构建产物。你可以从官方源码仓库拉取ui相关模块自己构建，也可以直接用社区里二次封装好的预构建包。我建议第一次集成时直接用官方源码构建，至少能保证和当前Flowable版本匹配。

构建命令本身没什么特殊之处，npm install、npm run build一把过。需要注意Node版本，老版本的Vue工程配太新的Node，经常会因为OpenSSL相关错误构建失败。官方文档里一般会说明推荐的Node大版本，老老实实按那个版本装就行，不要顺手升级到最新的Node。

构建产物是一堆js、css、html和静态图片，我把它统一放到src/main/resources/static/modeler-ui/目录下。Spring Boot会自动映射这个目录，访问路径是ip:port/modeler-ui/。如果你的后端接口有独立的context-path前缀，记得同步调整。

4.2 静态资源映射和路由模式选择

Modeler前端默认可能使用history路由模式，直接刷新某个二级路径会出现404，因为后端没有对应的路径映射。两种解决方案，要么后端加一个转发把未匹配的路径指到index.html，要么前端构建时改成hash路由。我在项目里选的是hash模式，简单省事，刷新不会出问题。

spring.mvc.static-path-pattern如果全局改过，Modeler静态目录的映射也会受影响。我把静态路径模式保留为默认的/static/**外，额外给modeler-ui加了资源映射：

@Configuration public class ModelerStaticConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/modeler-ui/**") .addResourceLocations("classpath:/static/modeler-ui/"); } }

这样访问路径非常直观，前端项目里请求后端API时，直接指向/api/flowable/model前缀，不用走官方那个复杂的路由。

4.3 把官方工具栏改成自己顺手的名字

Modeler官方界面默认是英文，属性面板里一堆Display name、Documentation字段。业务人员看英文会比较吃力，我在前端构建前改了Vue工程里的多语言文件，把常用字段的中文翻译补全。菜单按钮也在源码里重新映射过，比如把保存改成“保存模型”，部署改成“部署流程”。

这个改造要在构建前做，构建完之后再改编译好的js文件成本很高。更稳妥的做法是保留一份前端源码二开分支，后续要调整界面样式、按钮位置、加载事件，都从这份分支重新构建。不要直接改dist产物，打包后的代码一长串压缩字符串，可读性和可维护性都很差。

4.4 与后台菜单和iframe的衔接方式

我最终没有用iframe，而是让Modeler直接作为一个独立路由嵌进后台主框架。你在自己项目里如果用的是iframe嵌套，需要注意X-Frame-Options响应头，Spring Security默认会禁止跨域页面被iframe嵌入，表现出来就是菜单点进去一片空白，浏览器控制台有SecurityError。解决方式是关闭frameOptions或者设置为SAMEORIGIN。

另外，如果Modeler页面和后台主框架不在同一个端口，还会牵扯跨域。开发环境里可以用Vue代理转发，生产环境建议让Nginx统一入口，把/api和/modeler-ui都代理到后端服务，这样前后端始终同源，最省心。我用这种方式之后，整个嵌入过程没有出现过一次跨域报错。

5. 坑位实录：集成Flowable Modeler最容易翻车的五个地方

5.1 模型列表有的能打开有的打开为空

这个问题大概率出在编辑器JSON上。早期版本创建模型时如果只插入了一条ACT_RE_MODEL记录，没有初始化编辑器JSON，前端打开画布时就会拿到一个空对象。解决方法是统一在创建接口里生成最小JSON结构，不能只依赖前端另存为的逻辑。

排查时可以看数据库ACT_GE_BYTEARRAY表，对应模型的NAME_字段一查便知。如果发现json类型的数据是空的，补一次保存就能恢复。

5.2 保存时点按钮没反应，接口报500

我遇到的几次500都是BpmnJsonConverter转换时遇到了非法JSON节点。比如节点名称字段带了特殊字符，或者某个监听器配置结构不完整。这种情况前端画布上是看不出异常的，只能看后端日志里Jackson具体报哪一行，然后回前端源码里定位。

一个实用习惯是：保存前先让前端用内置校验规则跑一遍，有错误直接提示用户修正，而不是把带病数据送到后端。这个校验动作加到保存按钮的监听事件里，成本很低但非常管用。

5.3 Security配置冲突，整个后台访问被拦

如果你踩过这条路你一定懂这有多疼。引入官方UI全家桶后，它自带的安全配置会接管你的请求，明明登录成功一跳转又让你去登录。我见过有人为了兼容官方IDM，把自家登录体系改成Flowable的，最后绕了一大圈，权限管理还是一团糟。

如果自建接口路线，直接从源头避开这个坑。核心原则是在你的Spring Boot应用里不要引入flowable-ui-common这种会触发Spring Security自动配置的依赖，流程引擎本身不带UI安全体系，也就不存在冲突。

5.4 部署成功但流程定义启动报错

部署接口返回了流程定义，但启动流程实例时报错，最常见两个原因。一是部署时用的XML和当前引擎版本不兼容，比如6.x的模型部署到7.x的引擎上，节点属性解析失败。二是模型里引用了不存在的服务任务类，或者表达式写错了。建议部署成功后在模型列表里显示一个“验证”按钮，调用引擎的静态校验接口做一次语法级检查，避免业务人员画完图部署完，跑到运行时才发现问题。

5.5 生产环境模型数据丢失

数据库字符集和排序规则不统一是隐蔽杀手。MySQL默认字符集如果是utf8而不是utf8mb4，流程变量里存emoji或者生僻字时写入会静默失败或截断。Flowable模型表里存编辑器JSON是比较长的文本，更要保证字段类型和字符集到位。

我在初始化数据库时就固定了库、表两层字符集都是utf8mb4，并且用flyway管理历史表的增量脚本，后续无论测试还是生产环境，数据库结构都保持一致。这点看起来基础，但真的是很多线上事故的源头。

6. 把这套嵌入方案做稳定的几个进阶建议

6.1 静态资源版本化与缓存策略

Modeler前端工程经过多次改版后，js和css文件名会带上hash，这时候更新构建产物后浏览器仍可能加载旧文件。我建议在Nginx里为静态资源配置hash指纹和强缓存，index.html不缓存，带hash的js、css设置长时间缓存。这样发布新版本时，用户刷新页面就能拿到新资源，又不会每次刷新都重新下载一堆大文件。

6.2 给模型增加分类和标签位

官方Model表里有category字段，自建模型列表接口时我顺手把它用作分类。前台页面可以让不同部门的模型按分类筛选，后台保存时也可以强制校验Key的命名规范，比如统一带上业务前缀。这样模型多起来之后，管理界面不会变成一坨无序列表。

6.3 预览和校验能力尽量前置

我最后一段优化是在模型列表里加了预览入口。点击预览时后端直接把BPMN XML渲染成一个只读流程图展示给用户，业务人员不进入画图界面就能确认流程结构对不对。这个功能对审批流场景很友好，毕竟很多人只想看当前的图，并不想不小心改到模型。

写到最后的一点个人体会

Flowable的Modeler本身是个成熟好用的建模工具，界面化嵌入真正的难度从来不在画布本身，而在于怎么把官方UI的默认行为跟你自己的工程结构、权限体系、部署流程融合到一起。我做完这个项目最大的感受是：不要害怕自己写接口，Modeler甚至流程引擎最核心的操作，说到底就那么几个，自己封装一遍反而对Flowable的理解深了不少。

最后再分享一个小技巧：前端保存模型的按钮，尽量不要直接绑默认保存逻辑，而是监听模型修改事件，在真正调用后端接口前先做一次脏数据检测和XML导出试验。这个动作能拦住绝大部分“画图没问题但存不上”的软件疑难杂症。后续如果你还要嵌表单设计器或者流程仿真模块，这套自建接口加官方前端构建产物的组合方式完全可以复制过去，只是接口数量和字段复杂度会增加一些。