Activiti 流程圖獲取與可視化實戰指南

業務場景

Activiti 工作流引擎運行時生成的流程圖（BPMN 圖形）需在前端展示、高亮當前節點、支持審批軌跡追溯。本文介紹流程圖獲取的核心 API 與實現方案。

核心 API

1. 獲取流程定義圖片輸入流

@Autowired
private RepositoryService repositoryService;

public InputStream getProcessDiagram(String processDefinitionId) {
    // 獲取流程定義圖片資源名
    ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
        .processDefinitionId(processDefinitionId)
        .singleResult();
    
    String diagramResourceName = pd.getDiagramResourceName();
    if (diagramResourceName == null) {
        return null; // 無圖形定義
    }
    
    // 返回圖片輸入流
    return repositoryService.getResourceAsStream(pd.getDeploymentId(), diagramResourceName);
}

2. 獲取高亮座標（當前活動節點）

@Autowired
private RuntimeService runtimeService;

public Map> getHighlights(String processInstanceId) {
    // 獲取當前活動的執行實例
    List executions = runtimeService.createExecutionQuery()
        .processInstanceId(processInstanceId)
        .list();
    
    Map> highlights = new HashMap<>();
    for (Execution exe : executions) {
        String activityId = exe.getActivityId();
        if (activityId != null) {
            // 從 BPMN 模型解析座標
            BpmnModel bpmnModel = repositoryService.getBpmnModel(exe.getProcessDefinitionId());
            FlowElement element = bpmnModel.getFlowElement(activityId);
            if (element instanceof GraphicInfo) {
                GraphicInfo gi = (GraphicInfo) element;
                List coords = new ArrayList<>();
                coords.add(new int[]{(int)gi.getX(), (int)gi.getY(), 
                                   (int)(gi.getX() + gi.getWidth()), (int)(gi.getY() + gi.getHeight())});
                highlights.put(activityId, coords);
            }
        }
    }
    return highlights;
}

前端渲染方案

方案一：後端疊圖輸出（傳統）

@GetMapping("/process/diagram/{processInstanceId}")
public void generateDiagram(@PathVariable String processInstanceId, HttpServletResponse response) {
    // 1. 獲取原始圖片流
    InputStream imageStream = getProcessDiagram(processInstanceId);
    // 2. 獲取高亮座標
    Map> highlights = getHighlights(processInstanceId);
    
    // 3. 使用 Graphics2D 繪製高亮矩形
    BufferedImage image = ImageIO.read(imageStream);
    Graphics2D g2d = image.createGraphics();
    g2d.setColor(Color.RED);
    g2d.setStroke(new BasicStroke(3));
    for (List coords : highlights.values()) {
        for (int[] c : coords) {
            g2d.drawRect(c[0], c[1], c[2] - c[0], c[3] - c[1]);
        }
    }
    g2d.dispose();
    
    // 4. 輸出圖片
    response.setContentType("image/png");
    ImageIO.write(image, "png", response.getOutputStream());
}

方案二：前端 Canvas 疊加（推薦）

後端提供：

• 原始流程圖 URL：/api/process/image/{processDefinitionId}
• 高亮數據 JSON：/api/process/highlights/{processInstanceId}

前端使用 Canvas 或 SVG 疊加繪製，優點：

• 減輕後端壓力、支持交互（縮放、拖拽、工具提示）
• 高亮樣式可配置、支持動畫過渡
• 移動端適配更好

BPMN 模型座標解析關鍵點

// 獲取 BPMN 模型
BpmnModel bpmnModel = repositoryService.getBpmnModel(processDefinitionId);

// 遍歷所有流程元素獲取座標
Collection flowElements = bpmnModel.getMainProcess().getFlowElements();
for (FlowElement element : flowElements) {
    if (element instanceof GraphicInfo) {
        GraphicInfo gi = (GraphicInfo) element;
        // gi.getX(), gi.getY(), gi.getWidth(), gi.getHeight()
        // 元素 ID: element.getId()
        // 元素名稱: element.getName()
    }
}

// 連線座標（SequenceFlow）
for (SequenceFlow flow : bpmnModel.getMainProcess().getSequenceFlows()) {
    List waypoints = flow.getWaypoints();
    // waypoints 包含折線轉折點座標
}

完整 REST 接口設計

常見問題與解決

最佳實踐建議

1. 分離關注點：後端提供數據，前端負責渲染與交互
2. 緩存策略：流程定義圖片、BPMN 模型緩存（Redis/Caffeine），Key 含版本號
3. 座標標準化：規範建模工具導出座標精度（建議整數像素）
4. 權限控制：流程圖數據屬敏感業務信息，需鉴權
5. 版本兼容：支持多版本流程定義並存，Key 包含版本號

總結

Activiti 流程圖獲取核心在於 RepositoryService 讀取部署資源與 BpmnModel 解析圖形座標。現代架構推薦「後端提供數據 + 前端 Canvas/SVG 渲染」模式，實現高性能、可交互、易擴展的流程可視化能力。