# workflow

**Repository Path**: nask137/workflow

## Basic Information

- **Project Name**: workflow
- **Description**: 一个可编排的工作流框架
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-05
- **Last Updated**: 2025-12-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 工作流框架 (Workflow Framework)

[![Java](https://img.shields.io/badge/Java-17-orange.svg)](https://www.oracle.com/java/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.3-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![Maven](https://img.shields.io/badge/Maven-3.6+-blue.svg)](https://maven.apache.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## 📖 项目简介

这是一个基于 Spring Boot 的可扩展工作流执行框架，支持通过配置化的方式定义和执行复杂的业务流程。框架采用组件化设计，提供了丰富的内置组件，同时支持自定义组件扩展。

### ✨ 核心特性

- 🔧 **配置化工作流**：通过 JSON 配置定义工作流，无需编码
- 🧩 **组件化设计**：内置丰富组件，支持自定义扩展
- 🚀 **Spring Boot 集成**：完整的 Spring 生态支持
- 🔒 **线程安全**：执行上下文采用线程安全设计
- 📊 **数据持久化**：支持工作流定义的数据库存储和版本管理
- 🔄 **条件分支**：支持动态流转和条件判断
- ⚡ **高性能**：内存缓存 + 数据库持久化的混合架构
- 🛡️ **生产就绪**：完整的错误处理、日志记录和监控机制

## 🏗️ 架构设计

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   工作流定义     │    │   工作流执行器   │    │   组件注册表     │
│ WorkflowService │────│WorkflowExecutor │────│ComponentRegistry│
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   数据库存储     │    │   执行上下文     │    │   内置组件库     │
│   MySQL/H2     │    │ExecutionContext │    │  TaskComponent  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## 🚀 快速开始

### 环境要求

- Java 17+
- Maven 3.6+
- MySQL 8.0+ (可选，支持 H2 内存数据库)

### 安装步骤

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd workflow
   ```

2. **配置数据库**
   ```yaml
   # application.yml
   spring:
     datasource:
       url: jdbc:mysql://localhost:3306/workflow
       username: your_username
       password: your_password
       driver-class-name: com.mysql.cj.jdbc.Driver
   ```

3. **编译运行**
   ```bash
   mvn clean package
   java -jar target/workflow-1.0.4-SNAPSHOT-boot.jar
   ```

### 简单示例

```java
@Service
public class WorkflowExample {
    
    @Autowired
    private WorkflowService workflowService;
    
    @Autowired
    private WorkflowExecutor workflowExecutor;
    
    public void createAndExecuteWorkflow() {
        // 1. 创建工作流定义
        WorkflowDefinition workflow = new WorkflowDefinition();
        workflow.setWorkflowId("hello-world");
        workflow.setWorkflowName("Hello World 工作流");
        workflow.setVersion("1.0.0");
        
        // 2. 添加入口组件
        ComponentConfig entry = new ComponentConfig();
        entry.setId("entry");
        entry.setName("EntryComponent");
        entry.getOutputMapping().put("message", "greeting");
        workflow.addComponent("entry", entry);
        
        // 3. 添加出口组件
        ComponentConfig exit = new ComponentConfig();
        exit.setId("exit");
        exit.setName("ExitComponent");
        exit.getInputMapping().put("result", "greeting");
        workflow.addComponent("exit", exit);
        
        // 4. 设置流转关系
        workflow.addTransition("entry", "exit");
        
        // 5. 保存工作流定义
        workflowService.saveWorkflowDefinition(workflow);
        
        // 6. 执行工作流
        ExecutionContext context = new ExecutionContext();
        context.put("input", "Hello, Workflow!");
        
        ExecutionResult result = workflowExecutor.execute(workflow, context);
        System.out.println("执行结果: " + result.isSuccess());
    }
}
```

## 🧩 内置组件

| 组件名称 | 功能描述 | 使用场景 |
|---------|---------|----------|
| **EntryComponent** | 工作流入口点 | 数据初始化、参数验证 |
| **ExitComponent** | 工作流出口点 | 结果聚合、格式化输出 |
| **ConditionalComponent** | 条件判断 | 流程分支、业务规则 |
| **HttpRequestComponent** | HTTP 请求 | API 调用、数据获取 |
| **JavaScriptComponent** | JavaScript 执行 | 动态脚本、数据处理 |
| **DataTransformComponent** | 数据转换 | 格式转换、数据映射 |
| **DataValidatorComponent** | 数据验证 | 输入校验、业务验证 |
| **TimerComponent** | 定时器 | 延时执行、定时任务 |
| **ParallelExecutionComponent** | 并行执行 | 并发处理、性能优化 |
| **SubWorkflowComponent** | 子工作流 | 流程复用、模块化 |

## 📚 核心概念

### 工作流定义 (WorkflowDefinition)
包含工作流的基本信息、组件配置和流转关系：
```java
WorkflowDefinition workflow = new WorkflowDefinition();
workflow.setWorkflowId("my-workflow");
workflow.setWorkflowName("我的工作流");
workflow.setVersion("1.0.0");
```

### 组件配置 (ComponentConfig)
定义组件的输入输出映射和参数：
```java
ComponentConfig config = new ComponentConfig();
config.setId("http-request");
config.setName("HttpRequestComponent");
config.getInputMapping().put("url", "apiUrl");
config.getOutputMapping().put("response", "apiResult");
config.setParam("method", "GET");
```

### 执行上下文 (ExecutionContext)
在组件间传递数据的容器：
```java
ExecutionContext context = new ExecutionContext();
context.put("apiUrl", "https://api.example.com/data");
```

## 🔧 自定义组件开发

实现 `TaskComponent` 接口创建自定义组件：

```java
@Component("myCustomComponent")
public class MyCustomComponent implements TaskComponent {
    
    @Override
    public void execute(ExecutionContext context, ComponentConfig config) {
        // 获取输入参数
        String input = context.getInputValue("input", config, String.class);
        
        // 执行业务逻辑
        String result = processData(input);
        
        // 设置输出结果
        context.setOutputValue("result", result, config);
    }
    
    private String processData(String input) {
        // 自定义处理逻辑
        return "Processed: " + input;
    }
}
```

## 📁 项目结构

```
src/main/java/com/example/workflow/
├── WorkflowApplication.java          # Spring Boot 启动类
├── api/                              # 核心接口定义
│   └── TaskComponent.java            # 任务组件接口
├── aspect/                           # 切面相关
│   └── LoggingAspect.java            # 日志切面
├── component/                        # 内置组件实现
│   ├── EntryComponent.java           # 入口组件
│   ├── ExitComponent.java            # 出口组件
│   ├── ConditionalComponent.java     # 条件组件
│   ├── HttpRequestComponent.java     # HTTP请求组件
│   ├── JavaScriptComponent.java      # JavaScript组件
│   └── ...                           # 其他组件
├── config/                           # 配置相关
│   └── ComponentConfig.java          # 组件配置类
├── context/                          # 执行上下文
│   └── ExecutionContext.java         # 执行上下文类
├── engine/                           # 执行引擎
│   ├── WorkflowDefinition.java       # 工作流定义
│   ├── WorkflowExecutor.java         # 工作流执行器
│   └── ExecutionResult.java          # 执行结果
├── properties/                       # 配置属性
│   └── WorkflowProperties.java       # 工作流配置
├── registry/                         # 组件注册
│   └── ComponentRegistry.java        # 组件注册表
├── service/                          # 服务层
│   └── WorkflowService.java          # 工作流服务
└── spi/                              # 自动配置
    ├── WorkFlowComponentAutoConfiguration.java
    └── WorkFlowServiceAutoConfiguration.java
```

## 🔧 配置说明

### 数据库配置
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/workflow
    username: workflow_user
    password: workflow_pass
    driver-class-name: com.mysql.cj.jdbc.Driver
```

### 工作流配置
```yaml
workflow:
  preload-cache: true          # 是否预热缓存
  max-cache-size: 1000         # 最大缓存数量
  shutdown-timeout: 30         # 关闭超时时间(秒)
  force-sync-on-shutdown: true # 是否强制同步
```

## 📊 监控和日志

框架提供了完整的日志记录和监控功能：

- **执行日志**：详细记录工作流执行过程
- **性能监控**：统计执行时间和步骤数
- **错误追踪**：完整的异常堆栈信息
- **缓存统计**：内存使用和同步状态

## 🧪 测试

运行单元测试：
```bash
mvn test
```

运行集成测试：
```bash
mvn verify
```

## 📖 文档

- [工作流框架说明文档](workflow_frame/docs/工作流框架说明文档.md)
- [工作流服务使用指南](workflow_frame/docs/UnifiedWorkflowService使用指南.md)
- [依赖配置指南](workflow_frame/docs/DEPENDENCY_GUIDE.md)

## 🤝 贡献指南

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙋‍♂️ 支持

如果您在使用过程中遇到问题，请：

1. 查看 [文档](workflow_frame/docs/)
2. 搜索 [Issues](../../issues)
3. 创建新的 [Issue](../../issues/new)

## 🎯 路线图

- [ ] Web UI 管理界面
- [ ] 更多内置组件
- [ ] 分布式执行支持
- [ ] 可视化流程设计器
- [ ] 性能优化和监控增强

---