从0到1：Activiti工作流模型部署全解析（附实战代码）

在企业级应用开发中，工作流引擎是实现业务流程自动化的核心组件，而Activiti作为开源工作流领域的标杆框架，其模型部署机制直接决定了流程从设计到落地的效率。本文将基于Activiti的核心API，从模型部署的底层逻辑、完整流程到实战代码，带你全方位掌握这一关键操作。

一、模型部署的核心本质

模型部署是连接“流程设计”与“流程执行”的桥梁。在Activiti生态中，我们通过Modeler设计的流程模型（存储于act_re_model表）仅为“设计草稿”，需经过部署流程将其转换为可执行的流程定义（存储于act_re_procdef表），才能启动流程实例并执行业务逻辑。

简单来说，部署过程的核心是将JSON格式的模型配置转换为BPMN 2.0标准格式，并在Activiti的数据库中生成对应的部署记录、流程定义及二进制资源，形成完整的执行链路。

二、模型部署的核心流程与数据流向

Activiti的模型部署并非单一操作，而是涉及多表联动、格式转换的完整流程，其核心数据流向如下：

1. 数据准备：从数据库读取模型基础信息

部署的第一步是获取已设计完成的模型数据，包括两部分核心内容：

• 模型元信息：从act_re_model表读取模型名称、标识（key）、分类等基础属性，通过repositoryService.getModel(modelId)实现；
• 模型编辑器内容：从act_ge_bytearray表读取JSON格式的流程设计数据，通过repositoryService.getModelEditorSource(modelId)获取二进制流。

2. 格式转换：JSON转BPMNModel

模型设计器存储的JSON数据无法直接被Activiti执行，需通过BpmnJsonConverter工具类转换为框架可识别的BpmnModel对象。这一步是部署的核心，负责将可视化设计的节点、连线、网关等元素，映射为符合BPMN 2.0规范的流程定义结构。

3. 部署执行：生成流程定义与部署记录

通过repositoryService.createDeployment()构建部署构建器，设置部署名称、分类、标识等属性，并将BpmnModel对象以XXX.bpmn20.xml的格式添加到部署中，最终调用deploy()方法完成部署。

这一步会在数据库中生成三条关键数据：

• act_re_deployment：存储部署记录，生成唯一部署ID；
• act_re_procdef：存储可执行的流程定义，关联部署ID，是启动流程实例的核心依据；
• act_ge_bytearray：存储BPMN文件的二进制内容，与模型编辑器内容分属不同记录。

4. 关联更新：绑定模型与部署ID

部署完成后，需将生成的部署ID（deploy.getId()）赋值给模型对象，并通过repositoryService.saveModel(model)更新act_re_model表的DEPLOYMENT_ID_字段，实现模型与部署记录的关联，便于后续追溯和管理。

三、实战代码：标准化模型部署接口

基于Activiti 7.x版本，以下是优化后的标准化模型部署接口，解决了原代码中冗余保存、异常处理不规范等问题：

import org.activiti.bpmn.model.BpmnModel;
import org.activiti.engine.RepositoryService;
import org.activiti.engine.repository.Deployment;
import org.activiti.engine.repository.Model;
import org.activiti.editor.language.json.converter.BpmnJsonConverter;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

/**
 * 工作流模型部署接口
 */
@RestController
public class ModelDeploymentController {

    @Autowired
    private RepositoryService repositoryService;

    @Autowired
    private ObjectMapper objectMapper;

    /**
     * 模型部署：将设计好的模型转换为可执行流程定义
     * @param modelId 模型ID（act_re_model表主键）
     * @return 部署结果
     */
    @RequestMapping("/deploy/{modelId}")
    @ResponseBody
    public AjaxResult modelDeployment(@PathVariable String modelId) {
        // 校验模型ID合法性
        if (modelId == null || modelId.trim().isEmpty()) {
            return AjaxResult.error("模型ID不能为空");
        }

        try {
            // 1. 获取模型元信息与编辑器内容
            Model model = repositoryService.getModel(modelId);
            if (model == null) {
                return AjaxResult.error("未找到指定模型");
            }
            byte[] modelData = repositoryService.getModelEditorSource(modelId);
            if (modelData == null || modelData.length == 0) {
                return AjaxResult.error("模型内容为空，请完善流程设计");
            }

            // 2. JSON格式转换为BPMNModel
            JsonNode jsonNode = objectMapper.readTree(modelData);
            BpmnJsonConverter bpmnJsonConverter = new BpmnJsonConverter();
            BpmnModel bpmnModel = bpmnJsonConverter.convertToBpmnModel(jsonNode);

            // 校验BPMN模型合法性（避免无效流程部署）
            if (bpmnModel.getProcesses().isEmpty()) {
                return AjaxResult.error("流程模型中未包含有效流程，无法部署");
            }

            // 3. 执行部署操作
            Deployment deploy = repositoryService.createDeployment()
                    .category(model.getCategory()) // 继承模型分类
                    .name(model.getName()) // 继承模型名称
                    .key(model.getKey()) // 继承模型标识（保证唯一性）
                    .addBpmnModel(model.getKey() + ".bpmn20.xml", bpmnModel) // 生成BPMN文件
                    .deploy(); // 执行部署

            // 4. 更新模型与部署的关联关系
            model.setDeploymentId(deploy.getId());
            repositoryService.saveModel(model); // 仅需执行一次，更新act_re_model表

            return AjaxResult.success("部署成功", deploy.getId());
        } catch (Exception e) {
            // 日志记录（建议替换为日志框架，如SLF4J）
            e.printStackTrace();
            return AjaxResult.error("部署失败：" + e.getMessage());
        }
    }
}

四、关键细节与避坑指南

1. 数据存储校验

部署完成后，可通过以下SQL查询验证数据是否正确写入：

• 查看部署记录：SELECT * FROM act_re_deployment WHERE ID_ = '部署ID'；
• 查看流程定义：SELECT * FROM act_re_procdef WHERE DEPLOYMENT_ID_ = '部署ID'；
• 查看模型关联：SELECT ID_, NAME_, DEPLOYMENT_ID_ FROM act_re_model WHERE ID_ = '模型ID'。

2. 常见异常处理

• 模型内容为空：检查act_ge_bytearray表中是否存在该模型的编辑器内容，若不存在需重新设计流程；
• BPMN格式不合法：通常是流程设计存在逻辑错误（如无开始/结束节点、网关未连接完整），需返回Modeler重新调整；
• 模型标识重复：act_re_procdef表中KEY_ + VERSION_组合唯一，重复部署会自动升级版本号。

3. 性能与安全优化

• 避免重复部署：可在部署前添加校验，若模型已关联部署ID且流程定义未修改，直接返回成功；
• 日志规范：替换e.printStackTrace()为日志框架（如Logback），便于问题排查；
• 权限控制：为部署接口添加权限校验（如@PreAuthorize），仅允许管理员或流程设计师执行部署操作。

五、总结

Activiti模型部署的核心是“格式转换+数据持久化”，通过BpmnJsonConverter完成JSON到BPMNModel的转换，再通过repositoryService的部署接口生成流程定义，最终实现模型与部署的关联。整个过程涉及act_re_model、act_re_deployment、act_re_procdef、act_ge_bytearray四张核心表的联动，是工作流从设计到执行的关键一步。

掌握这一流程后，可进一步扩展功能，如部署状态查询、流程定义启停、版本管理等，构建完整的工作流生命周期管理体系。