1. 先搞清楚为什么要在 Spring Boot 里集成 bpmn-js如果你正在用 Spring Boot 开发一个需要流程审批、任务流转或者自动化编排的系统比如 OA、ERP、CRM 或者低代码平台那你大概率绕不开工作流引擎。Activiti、Flowable、Camunda 这几个主流的开源引擎功能强大但自带的流程设计器要么太简陋要么不符合国内用户的操作习惯。这时候一个能嵌入到你项目里的、专业的流程设计器就成了刚需。bpmn-js 就是这个问题的答案。它不是一个独立软件而是一个基于 Web 的 BPMN 2.0 标准建模工具库。简单说你可以把它像搭积木一样集成到你的 Spring Boot 应用的前端页面里无论是 Vue、React 还是原生页面让用户能在浏览器里直接拖拽节点、连线画出专业的流程图。画好的图可以直接保存为标准的 BPMN 2.0 XML 文件后端的工作流引擎如 Activiti 7能无缝识别和部署。所以这个主题的核心价值是为你的 Spring Boot 后端工作流应用配上一个前端可嵌入、标准兼容、且足够专业的可视化流程设计工具。它解决的不是“有没有流程引擎”的问题而是“如何让业务人员或实施人员方便地设计流程”的问题。如果你只关心后端 API 调用那可以跳过设计器但如果你要做成一个完整的产品设计器就是用户体验的关键一环。2. 集成前必须弄明白的技术选型和边界在动手写代码之前有几个关键点必须想清楚这决定了你后续集成的复杂度和最终效果。2.1 bpmn-js 的定位与能力边界首先bpmn-js 是一个“渲染工具包 Web 模型器”。它的核心能力是解析与渲染能将标准的 BPMN 2.0 XML 文件在网页上渲染成可视化的流程图。建模与编辑提供了一套完整的 UI 交互工具栏、调色板、属性面板等允许用户创建和修改流程图。模型导出将用户在界面上操作的图形转换回标准的 BPMN 2.0 XML。它的优点是标准兼容性好。因为严格遵循 BPMN 2.0用它设计的流程图可以确保被 Activiti、Flowable、Camunda 等引擎正确解析和执行包括复杂的网关、事件、子流程等。这对于需要处理复杂业务逻辑的 BPM业务流程管理项目至关重要。但它的缺点也很明显学习曲线陡峭定制化成本高。bpmn-js 底层依赖 diagram-js 和 bpmn-moddle 等库如果你想修改它的默认样式比如把节点改成圆角矩形、或者增加一个自定义的属性面板需要深入理解其扩展机制对前端开发能力要求不低。2.2 与其他流程设计器的对比在搜索材料里提到了几种其他方案这里帮你做个快速决策分析方案核心特点与 Spring Boot 工作流引擎集成难度适用场景bpmn-js专业、标准、功能全、可嵌入、定制难低。生成标准 BPMN XML引擎直接使用。专业的 BPM 系统、需要处理复杂流程并行、事件、补偿等。仿钉钉设计器交互友好、符合国内用户习惯、模型非标准高。需要前后端配合将自定义模型转换为 BPMN 标准模型。简单的 OA 审批流、追求极致用户体验的轻量级应用。基于 G6/AntV 自研灵活度高、可深度定制、需从头开发中高。同样存在模型转换问题且需要投入大量前端开发资源。对可视化有特殊要求如拓扑图、业务模型与 BPMN 差异巨大的场景。结论如果你的项目要求流程设计专业、标准且希望与 Activiti/Flowable 等后端引擎无缝对接bpmn-js 是集成路径最短、最稳妥的选择。仿钉钉和自研方案更适合流程简单或对交互有特殊定制化需求的场景。2.3 技术栈确认与环境准备基于标题“SpringBoot集成工作流引擎bpmnjs流程编辑器”我们假设一个典型的技术栈后端Spring Boot 2.7.x (兼容 JDK 8/11/17)工作流引擎Activiti 7 (或 Flowable 6/7, Camunda 7)前端考虑到集成简便性我们先用最朴素的方案——在 Spring Boot 的模板引擎如 Thymeleaf页面中直接引入 bpmn-js。这避免了 Vue/React 等框架的构建复杂度让你先聚焦于核心集成逻辑。构建工具Maven你需要准备一个能联网的开发环境用于下载 npm 包或 CDN 引入。IDE如 IntelliJ IDEA。确保本地已安装 Node.js可选如果你计划通过 npm 安装 bpmn-js 并打包资源。3. 第一步搭建 Spring Boot 基础项目并引入工作流引擎我们先从后端搭起确保工作流引擎能跑起来这是设计器能存图、部署的基础。3.1 创建 Spring Boot 项目并添加依赖使用 Spring Initializr 或 IDEA 直接创建一个 Spring Boot 项目。核心依赖如下pom.xmlparent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version !-- 选择一个稳定的 LTS 版本 -- relativePath/ /parent dependencies !-- Web 支持 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- 模板引擎用于承载前端页面 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependency !-- Activiti 7 Spring Boot Starter -- dependency groupIdorg.activiti/groupId artifactIdactiviti-spring-boot-starter/artifactId version7.1.0.M6/version !-- 注意版本建议与Spring Boot版本匹配 -- /dependency !-- 数据库这里用 H2 内存数据库方便演示 -- dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency !-- 可选用于测试 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies关键点解释使用activiti-spring-boot-starter能极大简化配置它会自动配置流程引擎、创建所需的数据表。先用 H2 内存数据库避免早期陷入数据库配置问题。生产环境再换成 MySQL/PostgreSQL。Thymeleaf 不是必须你也可以用纯 HTML 文件但集成在模板里更方便管理前后端交互。3.2 基础配置与验证在application.yml或application.properties中做最小化配置spring: thymeleaf: cache: false # 开发时关闭缓存修改页面实时生效 datasource: url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY-1 driver-class-name: org.h2.Driver username: sa password: h2: console: enabled: true # 开启 H2 控制台方便查看数据库 # Activiti 配置 activiti: database-schema-update: true # 自动更新数据库表 db-history-used: true # 使用历史表 history-level: audit # 历史记录级别 check-process-definitions: false # 启动时不检查 processes/ 目录下的BPMN文件创建一个简单的启动类然后启动应用。如果控制台没有报错并且能访问http://localhost:8080/h2-consoleJDBC URL 填jdbc:h2:mem:testdb看到以ACT_开头的表说明 Activiti 引擎集成成功。注意第一次启动时database-schema-update: true会让 Activiti 自动创建所有表。在生产环境建议设置为false或使用 Flyway/Liquibase 管理数据库版本。3.3 创建第一个流程定义 API为设计器做准备设计器最终需要把画好的流程图BPMN XML保存到后端并部署成可执行的流程定义。我们先写一个最简化的 Controller 来处理这个事。package com.example.workflow.controller; import org.activiti.api.process.model.ProcessDefinition; import org.activiti.api.process.runtime.ProcessRuntime; import org.activiti.engine.RepositoryService; import org.activiti.engine.repository.Deployment; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import org.springframework.web.multipart.MultipartFile; import java.io.IOException; import java.nio.charset.StandardCharsets; import java.util.HashMap; import java.util.Map; RestController RequestMapping(/api/process) public class ProcessDesignController { Autowired private RepositoryService repositoryService; Autowired private ProcessRuntime processRuntime; // Activiti 7 的 API /** * 部署一个 BPMN 2.0 XML 字符串 * param bpmnXml 流程定义的 XML 内容 * param name 流程名称 */ PostMapping(/deploy) public MapString, Object deployProcess(RequestParam String bpmnXml, RequestParam String name) { MapString, Object result new HashMap(); try { Deployment deployment repositoryService.createDeployment() .addString(name .bpmn20.xml, bpmnXml) .name(name) .deploy(); result.put(success, true); result.put(deploymentId, deployment.getId()); result.put(message, 流程部署成功); } catch (Exception e) { result.put(success, false); result.put(message, 部署失败: e.getMessage()); } return result; } /** * 获取已部署的流程定义列表 */ GetMapping(/definitions) public MapString, Object getProcessDefinitions() { MapString, Object result new HashMap(); // 使用 ProcessRuntime (Activiti 7) 或 RepositoryService (传统API) 查询 // 这里用 ProcessRuntime 示例 java.util.ListProcessDefinition definitions processRuntime.processDefinitions().list(); result.put(success, true); result.put(data, definitions); return result; } }这个 Controller 提供了两个关键接口POST /api/process/deploy接收前端设计器传来的 BPMN XML 字符串和流程名将其部署到 Activiti 引擎中。GET /api/process/definitions获取已部署的流程列表用于设计器加载已有流程进行编辑。为什么先写后端接口因为设计器的核心价值是“产出的图能被后端引擎使用”。先确保后端接收和部署 BPMN XML 的链路是通的前端集成才有意义。否则前端画得再漂亮图存不下来或部署不了也是白搭。4. 第二步在前端页面中集成 bpmn-js 设计器后端准备好了现在进入核心环节把 bpmn-js 嵌入到 Spring Boot 提供的前端页面里。4.1 方案选择CDN 引入 vs. NPM 构建对于快速集成和演示我强烈建议使用 CDN 引入。这能让你在 5 分钟内看到设计器界面避免陷入前端构建工具Webpack, Vite的配置泥潭。在src/main/resources/templates目录下创建一个designer.html文件如果你用 Thymeleaf也可以是designer.html。!DOCTYPE html html langzh-CN xmlns:thhttp://www.thymeleaf.org head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title流程设计器/title !-- 引入 bpmn-js 的 CSS 和 JS (使用 CDN) -- link relstylesheet hrefhttps://unpkg.com/bpmn-js14.0.0/dist/assets/diagram-js.css link relstylesheet hrefhttps://unpkg.com/bpmn-js14.0.0/dist/assets/bpmn-font/css/bpmn.css style * { margin: 0; padding: 0; } html, body, #canvas { height: 100%; width: 100%; overflow: hidden; } #toolbar { position: absolute; top: 10px; left: 10px; z-index: 100; background: rgba(255, 255, 255, 0.9); padding: 10px; border-radius: 4px; box-shadow: 0 2px 5px rgba(0,0,0,0.2); } button { margin-right: 5px; padding: 5px 10px; cursor: pointer; } .hidden { display: none; } /style /head body !-- 工具栏 -- div idtoolbar button onclicksaveDiagram()保存/button button onclickloadDiagram()加载/button button onclickdeployProcess()部署/button input typefile idfileInput classhidden accept.bpmn,.xml onchangehandleFileSelect(event) button onclickdocument.getElementById(fileInput).click()打开文件/button input typetext idprocessName placeholder输入流程名称 valueMyProcess /div !-- 画布容器 -- div idcanvas/div !-- 引入 bpmn-js 及相关依赖 -- script srchttps://unpkg.com/bpmn-js14.0.0/dist/bpmn-modeler.development.js/script script srchttps://unpkg.com/jquery3.6.0/dist/jquery.min.js/script !-- 方便使用 Ajax -- script // 全局变量 let bpmnModeler null; let currentXml ; // 页面加载完成后初始化 window.onload function() { // 初始化 bpmn-js 建模器 bpmnModeler new BpmnJS({ container: #canvas }); // 创建一个空的流程图 createNewDiagram(); }; // 创建一个新的空白流程图 async function createNewDiagram() { try { const result await bpmnModeler.createDiagram(); console.log(Diagram created); // 可以在这里设置一些初始属性 } catch (err) { console.error(Could not create diagram, err); } } // 保存当前图表为 BPMN XML async function saveDiagram() { try { const { xml } await bpmnModeler.saveXML({ format: true }); currentXml xml; // 提示保存成功这里可以扩展为下载文件 alert(流程图已保存为 XML (可在控制台查看)); console.log(BPMN XML:, xml); } catch (err) { console.error(Failed to save diagram, err); alert(保存失败: err.message); } } // 从后端加载一个已有的流程定义 async function loadDiagram() { // 这里简化处理实际应从后端API获取流程定义列表供用户选择 // 假设我们有一个已知的流程定义ID或XML内容 // 示例直接打开一个本地示例文件通过文件选择器 document.getElementById(fileInput).click(); } // 处理文件选择 function handleFileSelect(event) { const file event.target.files[0]; if (!file) return; const reader new FileReader(); reader.onload function(e) { const xml e.target.result; openDiagram(xml); }; reader.readAsText(file); } // 将 XML 加载到设计器中 async function openDiagram(xml) { try { await bpmnModeler.importXML(xml); currentXml xml; console.log(Diagram imported); } catch (err) { console.error(Failed to import diagram, err); alert(打开失败: err.message); } } // 部署流程到后端 async function deployProcess() { if (!currentXml) { alert(请先保存流程图); return; } const processName document.getElementById(processName).value.trim(); if (!processName) { alert(请输入流程名称); return; } // 调用后端部署接口 $.ajax({ url: /api/process/deploy, type: POST, data: { bpmnXml: currentXml, name: processName }, success: function(response) { if (response.success) { alert(流程部署成功部署ID: response.deploymentId); } else { alert(部署失败: response.message); } }, error: function(xhr, status, error) { alert(请求失败: error); } }); } /script /body /html4.2 关键代码解析与避坑点CDN 版本选择我们引入了bpmn-modeler.development.js这是包含了建模器完整功能的开发版。生产环境可以考虑引入压缩版.production.min.js并考虑自托管。初始化时机必须在window.onload或 DOM 准备就绪后初始化BpmnJS实例并指定画布容器#canvas。创建空白图bpmnModeler.createDiagram()会创建一个只包含一个开始事件的空流程图。这是设计器的起点。保存 XMLbpmnModeler.saveXML()是核心方法它返回一个 Promise解析后得到格式化好的 BPMN 2.0 XML 字符串。务必保存到变量如currentXml中这是后续部署到后端的依据。导入 XMLbpmnModeler.importXML(xmlString)用于将已有的 BPMN XML 加载到设计器中进行编辑。这是实现“打开”或“编辑已有流程”功能的关键。部署调用通过 jQuery 的$.ajax你也可以用fetch或axios调用我们之前写好的/api/process/deploy接口将currentXml和流程名称传过去。常见问题排查设计器不显示检查浏览器控制台F12是否有 JS 错误。最常见的是 CDN 资源加载失败网络问题或者#canvas容器的 CSS 高度/宽度为 0。保存/导入时报错检查传入importXML的字符串是否是有效的 BPMN 2.0 XML。可以从 bpmn.io 官网下载一个示例 XML 文件测试。部署接口 404确保 Spring Boot 应用已启动且 Controller 的路径/api/process/deploy正确。检查浏览器网络请求面板。跨域问题因为我们的前端页面和后端服务同源都是localhost:8080所以不会有跨域问题。如果你将前端单独部署则需要配置 Spring Boot 的 CORS。4.3 创建访问页面的 Controller为了让 Spring Boot 能渲染这个 HTML 页面我们需要一个简单的 Controller 来映射路由。package com.example.workflow.controller; import org.springframework.stereotype.Controller; import org.springframework.web.bind.annotation.GetMapping; Controller public class PageController { GetMapping(/designer) public String designer() { return designer; // 对应 templates/designer.html } }现在启动你的 Spring Boot 应用访问http://localhost:8080/designer。你应该能看到一个完整的 bpmn-js 流程设计器界面包含左侧的工具调色板Palette和中间的画布。5. 第三步实现设计器的核心功能与前后端联调有了基础界面我们需要完善功能让它真正可用。5.1 增强设计器属性面板与自定义基础的 bpmn-js 建模器已经提供了大部分 BPMN 元素。但通常我们需要为任务节点添加自定义业务属性比如“审批人”、“表单Key”、“超时时间”等。这需要用到 bpmn-js 的“属性面板”扩展。由于通过 CDN 引入扩展相对复杂。一个更实用的初级方案是利用 bpmn-js 的modeling和elementRegistry服务通过编程方式设置属性。修改designer.html中的脚本增加一个设置任务节点属性的函数// 获取 bpmn-js 内部服务 function getModelerServices() { return bpmnModeler.get(modeling, elementRegistry); } // 示例为选中的元素设置一个自定义属性 function setCustomProperty(elementId, key, value) { if (!bpmnModeler) return; const { modeling, elementRegistry } getModelerServices(); const element elementRegistry.get(elementId); if (element) { // 使用 modeling.updateProperties 来更新元素业务属性 modeling.updateProperties(element, { [key]: value }); console.log(Set property ${key}${value} for element ${elementId}); } else { console.warn(Element with id ${elementId} not found); } } // 监听元素选择变化以便在UI上显示当前选中元素的属性 bpmnModeler.on(selection.changed, function(event) { const newSelection event.newSelection; if (newSelection newSelection.length 0) { const element newSelection[0]; console.log(Selected element:, element.id, element.type); // 这里可以更新一个自定义的属性编辑面板 // document.getElementById(prop-key).value ; // document.getElementById(prop-value).value ; } });在实际项目中你需要构建一个更友好的属性编辑 UI并与这些函数联动。这涉及到更深入的前端开发超出了本文“集成”的范围但方向是监听元素选择事件 - 获取元素类型和现有属性 - 渲染对应的表单 - 用户修改后调用modeling.updateProperties更新。5.2 完善后端流程定义的查询与删除设计器通常还需要“打开已有流程”和“删除流程”的功能。我们来完善后端接口。在ProcessDesignController中增加/** * 根据部署ID删除流程部署 */ DeleteMapping(/deployment/{deploymentId}) public MapString, Object deleteDeployment(PathVariable String deploymentId, RequestParam(defaultValue false) boolean cascade) { // cascadetrue 会级联删除流程实例、历史数据等 MapString, Object result new HashMap(); try { repositoryService.deleteDeployment(deploymentId, cascade); result.put(success, true); result.put(message, 部署删除成功); } catch (Exception e) { result.put(success, false); result.put(message, 删除失败: e.getMessage()); } return result; } /** * 获取指定流程定义的 BPMN XML */ GetMapping(/definition/{processDefinitionId}/xml) public MapString, Object getProcessDefinitionXml(PathVariable String processDefinitionId) { MapString, Object result new HashMap(); try { // 通过 RepositoryService 获取流程定义资源 org.activiti.engine.repository.ProcessDefinition pd repositoryService.createProcessDefinitionQuery() .processDefinitionId(processDefinitionId) .singleResult(); if (pd ! null) { String resourceName pd.getResourceName(); InputStream resourceStream repositoryService.getResourceAsStream(pd.getDeploymentId(), resourceName); String bpmnXml new String(resourceStream.readAllBytes(), StandardCharsets.UTF_8); result.put(success, true); result.put(data, bpmnXml); } else { result.put(success, false); result.put(message, 流程定义不存在); } } catch (Exception e) { result.put(success, false); result.put(message, 获取XML失败: e.getMessage()); } return result; }前端相应地增加调用这些 API 的函数例如在加载流程时先调用GET /api/process/definitions列出流程用户选择后再调用GET /api/process/definition/{id}/xml获取 XML 并调用openDiagram。5.3 联调测试完整的“设计-保存-部署”流程现在进行端到端测试访问页面打开http://localhost:8080/designer。设计流程从左侧调色板拖拽一个“开始事件”、“用户任务”和“结束事件”到画布并用连线连接它们。保存 XML点击“保存”按钮浏览器控制台会打印出生成的 BPMN XML。检查 XML 中是否包含了你的图形元素。部署流程在输入框输入流程名称如“请假流程”点击“部署”按钮。观察浏览器网络请求确认POST /api/process/deploy调用成功并收到包含deploymentId的成功响应。验证部署方法一调用GET /api/process/definitions查看返回的列表中是否有你刚部署的流程。方法二访问 H2 控制台 (http://localhost:8080/h2-console)查询ACT_RE_PROCDEF表应该能看到一条新的流程定义记录。加载编辑可选实现一个简单的流程列表选择功能选择已部署的流程调用GET /api/process/definition/{id}/xml获取 XML再调用openDiagram加载到设计器中确认可以编辑。如果以上步骤都成功恭喜你你已经完成了 Spring Boot、工作流引擎和 bpmn-js 设计器最核心的集成闭环。6. 生产环境考量与进阶优化方向上面的演示让你跑通了最小可行集成。但要用于实际项目还需要考虑更多。6.1 前端资源管理从 CDN 到自托管CDN 方便演示但在生产环境存在稳定性、安全性和版本锁定问题。建议将 bpmn-js 及其依赖通过 npm 管理并打包到你的前端资源中。初始化前端项目在你的 Spring Boot 项目根目录下或单独的前端项目中执行npm init -y。安装依赖npm install bpmn-js --save构建与引入使用 Webpack/Vite 等工具打包将生成的 JS/CSS 文件放入 Spring Boot 的src/main/resources/static目录下然后在 HTML 中引用这些本地文件。这样可以更好地控制版本并支持离线使用。6.2 设计器功能扩展基础建模器可能不够用你需要安装额外的 bpmn-js 模块bpmn-js-properties-panel: 官方属性面板提供标准的 BPMN 属性编辑。camunda-bpmn-moddle: 如果你使用 Camunda 引擎需要这个来支持 Camunda 扩展属性。对于 Activiti/Flowable社区也有相应的moddle描述文件用于支持其扩展属性。安装这些模块后需要在初始化BpmnJS时进行配置和注入这需要一定的前端工程化能力。6.3 后端部署的健壮性文件存储上述例子将 BPMN XML 作为字符串直接传给引擎部署。在生产中你可能需要将 XML 文件持久化到数据库或文件系统中并关联业务元数据如分类、版本、创建者。版本控制工作流引擎本身支持流程定义的版本管理通过key和version。你的设计器界面可能需要支持“另存为新版本”或“发布”的概念。权限控制设计器页面和部署 API 需要加入权限校验确保只有有权限的用户才能设计或部署流程。异步部署与状态反馈对于复杂的流程部署可能耗时。可以考虑将部署操作异步化并通过 WebSocket 或轮询给前端反馈状态。输入验证与安全性务必对前端传入的 BPMN XML 进行基本的验证防止恶意或错误的 XML 导致引擎解析错误。6.4 与具体业务表单的集成这是最复杂的一环。bpmn-js 设计器负责定义流程的“骨架”节点、流向而每个“用户任务”节点具体展示什么表单、有哪些字段通常需要额外的“表单设计器”来定义。你需要建立流程定义与表单定义的关联关系例如在用户任务上设置一个formKey属性并在流程运行时由你的业务系统根据formKey渲染对应的表单。6.5 监控与问题排查集成后要关注以下几点浏览器性能当流程图非常复杂节点数 200时bpmn-js 的渲染和操作可能会变慢。需要进行性能测试和优化。XML 兼容性确保 bpmn-js 生成的 XML 与你使用的 Activiti/Flowable 版本完全兼容。有时新版本 bpmn-js 生成的扩展属性旧版引擎可能不支持。错误处理对importXML和saveXML等操作做好异常捕获和用户友好的提示。7. 总结从集成到实用的关键思维把 bpmn-js 拖进 Spring Boot 项目里显示出来只是第一步。真正让它产生价值需要你把它当作一个需要深度定化的“产品组件”来对待而不是一个即插即用的黑盒。我建议按这个顺序推进先跑通用本文的 CDN 方案最快速度让设计器显示、画图、保存、部署的闭环跑起来。这是建立信心的关键。再固化将前端资源本地化构建稳定的前端工程环境锁定 bpmn-js 版本。后定制根据你的业务需求逐步扩展属性面板、定制元素样式、增加自定义工具栏按钮。这是一个长期迭代的过程。连业务将流程定义与你的业务表单、权限体系、组织架构打通。这是工作流系统能否落地的核心。最后记住一个排查铁律当设计器画好的图部署后无法正常启动或执行时不要第一时间怀疑设计器或引擎。而是按这个顺序检查看 XML把设计器保存的原始 XML 拿出来格式是否规范是否包含了必要的元素如 process id看引擎日志部署时引擎是否报错错误信息是否指向某个特定的元素或属性简化验证用一个极简的流程图只有开始和结束事件测试确认基础链路没问题再逐步增加复杂节点。这个集成方案为你提供了一个坚实且标准化的起点。基于它你可以构建出从流程设计、部署到运行、监控的完整工作流应用。