FixFlow项目API使用指南：从基础到实践

一、FixFlow API概述

FixFlow作为一款强大的流程引擎，其API设计遵循了直观易用的原则。整个API体系围绕ProcessEngine核心对象构建，通过获取不同的服务接口来实现各类流程操作。

1.1 核心服务接口

FixFlow提供了七大核心服务接口，每个接口都有明确的职责划分：

1. ModelService - 负责流程模型的定义和部署
2. RuntimeService - 处理流程实例的运行时操作
3. TaskService - 管理任务实例和任务相关操作
4. FormService - 处理表单相关功能
5. HistoryService - 提供历史数据查询
6. IdentityService - 管理用户和组织结构
7. ScheduleService - 处理定时任务

这些服务接口的设计借鉴了业界成熟方案，使得有相关经验的开发者能够快速上手。

二、API基础使用

2.1 获取流程引擎实例

// 获取默认流程引擎实例
ProcessEngine processEngine = ProcessEngineManagement.getDefaultProcessEngine();

流程引擎实例是线程安全的单例对象，整个应用只需要一个实例即可。

2.2 获取服务接口

// 获取各种服务接口
ModelService modelService = processEngine.getModelService();
RuntimeService runtimeService = processEngine.getRuntimeService();
TaskService taskService = processEngine.getTaskService();

三、数据库连接管理

FixFlow提供了灵活的数据库连接管理机制，支持外部传入连接和内部创建连接两种方式。

3.1 外部连接传递

// 创建外部内容对象
ExternalContent externalContent = new ExternalContent();
// 设置操作用户
externalContent.setAuthenticatedUserId("user123");
// 设置数据库连接
externalContent.setConnection(connection);
// 应用到流程引擎
processEngine.setExternalContent(externalContent);

3.2 完整的事务控制示例

Connection connection = null;
try {
    // 获取数据库配置
    DataBase dataBase = processEngine.getProcessEngineConfiguration().getSelectedDatabase();
    
    // 创建连接
    Class.forName(dataBase.getDriverClassName());
    connection = DriverManager.getConnection(
        dataBase.getUrl(), 
        dataBase.getUsername(), 
        dataBase.getPassword());
    connection.setAutoCommit(false);
    
    // 设置到流程引擎
    ExternalContent externalContent = new ExternalContent();
    externalContent.setAuthenticatedUserId("user123");
    externalContent.setConnection(connection);
    processEngine.setExternalContent(externalContent);
    
    // 执行业务和流程操作
    // ...
    
    connection.commit();
} catch (Exception e) {
    if(connection != null) connection.rollback();
    throw e;
} finally {
    if(connection != null) {
        processEngine.contextClose(true, false);
        connection.close();
    }
}

四、完整流程操作示例

4.1 流程部署

// 通过ZIP文件部署流程
String deploymentId = modelService.deploymentByZip(
    "com/founder/fix/fixflow/test/engine/api/model/Process_TaskServiceTest.zip");

4.2 流程启动

// 创建启动命令
StartProcessInstanceCommand command = new StartProcessInstanceCommand();
command.setProcessDefinitionKey("Process_TaskServiceTest");
command.setBusinessKey("order_123");
command.setStartAuthor("user123");

// 启动流程
ProcessInstance instance = runtimeService.noneStartProcessInstance(command);

4.3 任务处理

// 查询任务
List<TaskInstance> tasks = taskService.createTaskQuery()
    .taskAssignee("user123")
    .processInstanceId(instanceId)
    .taskNotEnd()
    .list();

// 完成任务
ExpandTaskCommand completeCommand = new ExpandTaskCommand();
completeCommand.setCommandType("general");
completeCommand.setUserCommandId("HandleCommand_2");
completeCommand.setTaskId(tasks.get(0).getId());
taskService.expandTaskComplete(completeCommand, null);

五、查询API详解

FixFlow提供了强大的查询API，支持各种复杂查询场景。

5.1 基础查询

// 创建查询
ProcessInstanceQuery query = runtimeService.createProcessInstanceQuery();
// 设置条件
query.processDefinitionKey("Process_TaskServiceTest")
     .initiatorLike("user123")
     .orderByStartTime().desc();
// 执行查询
List<String> instances = query.listPage(1, 5);

5.2 扩展查询

当内置查询不满足需求时，可以使用扩展查询：

// 创建扩展查询
QueryExpandTo expand = new QueryExpandTo();
// 添加扩展字段
expand.setFieldSql("fixflow_def_processdefinition.PROCESS_NAME");
// 添加JOIN语句
expand.setLeftJoinSql("left join fixflow_def_processdefinition on processdefinition_id = fixflow_def_processdefinition.process_id");
// 应用到查询
query.queryExpandTo(expand);

六、测试最佳实践

FixFlow提供了完善的测试支持，建议测试类继承AbstractFixFlowTestCase。

6.1 测试类示例

@Deployment(resources = {"test/process.bpmn"})
public class MyProcessTest extends AbstractFixFlowTestCase {
    
    @Test
    public void testProcess() {
        // 测试代码
    }
}

6.2 测试要点

1. 继承AbstractFixFlowTestCase自动处理引擎初始化和清理
2. 使用@Deployment注解简化流程部署
3. 每个测试方法独立运行，互不影响

七、总结

FixFlow API设计兼顾了易用性和灵活性，通过本文的介绍，开发者可以掌握：

1. 核心API的使用方法
2. 数据库连接管理的最佳实践
3. 完整流程的操作示例
4. 强大的查询功能
5. 高效的测试方法

对于更复杂的使用场景，建议参考官方提供的完整测试用例，它们覆盖了API的绝大多数功能点。