Activiti Xugudb Adapter

Activiti 工作流引擎 XuguDB 适配指南

概述

本指南详细介绍如何将 Activiti 工作流引擎与虚谷数据库（XuguDB）集成，包括完整的配置流程、使用示例和最佳实践。Activiti 是一个轻量级的工作流和 BPM 平台，支持 BPMN 2.0 标准。

快速开始

1. 获取适配版 Activiti

由于官方 Activiti 不支持 XuguDB，需要使用虚谷提供的适配版本：

# 克隆适配版源码
git clone https://github.com/Xugu-Open-Source/activiti-5.2.1.git

# 安装到本地 Maven 仓库
cd activiti-5.2.1
mvn clean install -DskipTests

2. 添加 Maven 依赖

    
    
        org.activiti
        activiti-engine
        5.2.1-xugu
    
    
    
    
        com.xugudb
        xugu-jdbc
        12.3.4
    
    
    
    
        org.springframework.boot
        spring-boot-starter-web
    
    
    
    
        com.zaxxer
        HikariCP
    

3. 配置数据源

在 application.yml 中配置：

spring:
  datasource:
    driver-class-name: com.xugu.cloudjdbc.Driver
    url: jdbc:xugu://localhost:5137/activiti_db?useUnicode=true&characterEncoding=utf-8&serverTimezone=UTC&nullCatalogMeansCurrent=true&keyword_filter=LINK
    username: SYSDBA
    password: SYSDBA
    hikari:
      minimum-idle: 5
      maximum-pool-size: 20
  
  activiti:
    database-schema-update: true
    check-process-definitions: false

配置详解

数据源配置参数

| 参数 | 说明 | 推荐值 | |------|------|--------| | driver-class-name | XuguDB JDBC 驱动类 | com.xugu.cloudjdbc.Driver | | url | 数据库连接 URL | jdbc:xugu://host:port/db?params | | database-schema-update | 表结构更新策略 | true（自动创建/更新） | | check-process-definitions | 启动时检查流程定义 | false（开发环境） |

关键 URL 参数

• useUnicode=true&characterEncoding=utf-8：字符编码
• serverTimezone=UTC：时区设置
• nullCatalogMeansCurrent=true：元数据 catalog 参数处理
• keyword_filter=LINK：过滤关键字冲突

流程定义与部署

创建 BPMN 流程文件

在 src/main/resources/processes/ 目录下创建 .bpmn20.xml 文件：

部署流程定义

@Service
public class ProcessService {
    
    @Autowired
    private RepositoryService repositoryService;
    
    // 部署流程
    public String deployProcess(String bpmnFile) {
        Deployment deployment = repositoryService.createDeployment()
                .addClasspathResource(bpmnFile)
                .name("请假流程")
                .deploy();
        return deployment.getId();
    }
}

流程操作

启动流程实例

@Autowired
private RuntimeService runtimeService;

public String startProcess(String processKey, Map variables) {
    ProcessInstance instance = runtimeService.startProcessInstanceByKey(processKey, variables);
    return instance.getId();
}

任务管理

@Autowired
private TaskService taskService;

// 查询待办任务
public List getTasks(String assignee) {
    return taskService.createTaskQuery()
            .taskAssignee(assignee)
            .list();
}

// 完成任务
public void completeTask(String taskId, Map variables) {
    taskService.complete(taskId, variables);
}

历史查询

@Autowired
private HistoryService historyService;

// 查询历史流程实例
public List getHistoryProcesses(String processKey) {
    return historyService.createHistoricProcessInstanceQuery()
            .processDefinitionKey(processKey)
            .orderByProcessInstanceEndTime().desc()
            .list();
}

Spring Boot 集成

配置类

@Configuration
@EnableActiviti
public class ActivitiConfig {
    
    @Bean
    public ProcessEngineConfiguration processEngineConfiguration(DataSource dataSource) {
        SpringProcessEngineConfiguration config = new SpringProcessEngineConfiguration();
        config.setDataSource(dataSource);
        config.setDatabaseSchemaUpdate("true");
        config.setDatabaseType("mysql"); // XuguDB 使用 MySQL 兼容模式
        return config;
    }
}

启动类

@SpringBootApplication
public class ActivitiApplication {
    public static void main(String[] args) {
        SpringApplication.run(ActivitiApplication.class, args);
    }
}

数据库表结构

Activiti 在 XuguDB 中自动创建以下表：

• ACTRE*：流程定义存储
• ACTRU*：运行时数据
• ACTHI*：历史数据
• ACTGE*：通用数据

性能优化

1. 数据库索引

CREATE INDEX idx_task_assignee ON ACT_RU_TASK(ASSIGNEE_);
CREATE INDEX idx_task_process ON ACT_RU_TASK(PROC_INST_ID_);

2. 连接池调优

spring:
  datasource:
    hikari:
      maximum-pool-size: 30
      minimum-idle: 10
      idle-timeout: 60000

3. 查询优化

// 使用分页
List tasks = taskService.createTaskQuery()
        .taskAssignee("user1")
        .listPage(0, 20);

故障排除

常见问题

1. 表创建失败：确保使用适配版 Activiti（v5.2.1-xugu）
2. 连接超时：调整连接池 connection-timeout 参数
3. 关键字冲突：JDBC URL 添加 keyword_filter=LINK

日志配置

最佳实践

1. 使用清晰的流程 ID 和名称
2. 为任务添加文档说明
3. 合理使用事务管理
4. 定期清理历史数据
5. 监控流程实例数量

资源

• 示例项目：https://github.com/Xugu-Open-Source/xugu-activiti-demo
• 官方文档：https://docs.xugudb.com/content/ecosystem/orm/java/activiti
• Activiti 文档：https://www.activiti.org/userguide/

---

注意：本指南基于 Activiti v5.2.1-xugu 适配版本，确保使用正确的版本以避免兼容性问题。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kourou25
• Source: kourou25/xugudb-dev-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.