# flow_arch

**Repository Path**: ddddbb/flow_arch

## Basic Information

- **Project Name**: flow_arch
- **Description**: 架构 = 流程结构
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-15
- **Last Updated**: 2025-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flow Arch - 分布式事务流程框架

<div align="center">

![GitHub](https://img.shields.io/badge/version-1.0--SNAPSHOT-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Java](https://img.shields.io/badge/Java-8%2B-orange)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.7.3-green)

**企业级分布式事务流程框架，支持多种流程编排模式**

[快速开始](#快速开始) • [架构说明](#架构模式对比) • [API文档](#api-文档) • [示例项目](./examples)

</div>

## 项目概述

Flow Arch 是一个企业级分布式事务流程框架，提供多种流程编排模式来解决复杂业务场景中的一致性问题。

### 核心特性

- **🔄 多种流程模式**: 支持 Pipeline、SAGA、状态机、Process Control 四种流程编排模式
- **🛡️ 强一致性保证**: 基于状态机和补偿机制确保分布式事务的最终一致性
- **⚡ 高性能异步**: 支持异步执行和状态持久化，适用于长流程业务
- **🔧 灵活配置**: 支持重试策略、失败处理、状态管理等可配置化
- **📊 完整监控**: 提供详细的执行日志和状态追踪
- **🔌 Spring 集成**: 无缝集成 Spring Boot 生态

### 适用场景

- **金融交易系统**: 需要严格一致性保证的支付、清算、结算流程
- **电商订单系统**: 复杂的订单处理、库存扣减、支付流程
- **工作流引擎**: 企业级业务流程自动化
- **微服务编排**: 分布式服务间的事务协调

### 技术栈

- **核心框架**: Spring Boot 2.7.3
- **构建工具**: Maven 3.x
- **JDK版本**: 支持 Java 8/11/17
- **测试框架**: JUnit 5 + Mockito

## 架构模式对比

| 架构模式   | 拓扑结构 | 实时性 | 失败处理 | 一致性保证 | 状态持久化 | 典型应用场景             |
|--------|------|-----|------|-------|-------|--------------------|
| `Saga` | 线性   | 否   | 回滚   | 保证    | 有     | 金融交易等严格一致性场景       |
| `状态机`  | DAG  | 是   | 抛出异常 | 不保证   | 无     | 线程池等高吞吐量场景         |
| `PC`   | DAG  | 否   | 重试   | 保证    | 有     | 长流程订单，需容错降级的高一致性场景 |

![架构示意图](doc/PC、状态机架构示意图.png)
*图1: PC、状态机架构示意图 *

![状态机示意图](doc/pipeline架构示意图.png)  
*图2: pipeline架构示意图 *

![SAGA示意图](doc/SAGA示意图.png)  
*图3: SAGA事务架构示意图 *

## 快速开始

### 环境要求

- JDK 8+
- Maven 3.6+
- Spring Boot 2.x

### 1. 添加依赖

```xml
<dependency>
    <groupId>io.ddbm.flow</groupId>
    <artifactId>flow-saga</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>
```

### 2. 定义业务动作

```java
@Component
public class PaymentAction implements SagaAction {
    
    @Override
    public void execute(SagaContext context) {
        // 执行支付逻辑
        log.info("执行支付: {}", context.getBusinessId());
    }
    
    @Override
    public void rollback(SagaContext context) {
        // 支付回滚逻辑
        log.info("回滚支付: {}", context.getBusinessId());
    }
    
    @Override
    public ActionResult queryExecuteStatus(SagaContext context) {
        // 查询支付执行状态
        return ActionResult.SUCCESS;
    }
    
    @Override
    public ActionResult queryRollbackStatus(SagaContext context) {
        // 查询支付回滚状态
        return ActionResult.SUCCESS;
    }
}
```

### 3. 配置流程

```java
@Configuration
public class SagaConfiguration {
    
    @Bean
    public SagaFlow orderProcessFlow() {
        return SagaFlow.builder()
            .flowCode("order-process")
            .flowName("订单处理流程")
            .actions(Arrays.asList(
                InventoryAction.class,    // 库存扣减
                PaymentAction.class,      // 支付处理
                OrderConfirmAction.class  // 订单确认
            ))
            .build();
    }
}
```

### 4. 执行流程

```java
@Service
public class OrderService {
    
    @Autowired
    private SagaManager sagaManager;
    
    public void processOrder(Long orderId) {
        // 启动SAGA流程
        sagaManager.execute("order-process", orderId, SagaEvent.START);
        
        // 查询流程状态
        SagaStatus status = sagaManager.getStatus("order-process", orderId);
        log.info("流程状态: {}", status);
    }
}

### 5. 执行日志示例

```
2025-08-15 22:25:16.709 DEBUG [main] 收到请求:1,test
2025-08-15 22:25:16.715 INFO  [main] test,1,ImportAction,execute
2025-08-15 22:25:16.717 INFO  [main] test,1,ImportAction,executeQuery:SU
2025-08-15 22:25:16.718 INFO  [main] test,1,ImportAction==>ClearAction
2025-08-15 22:25:16.718 INFO  [main] test,1,ClearAction,execute
2025-08-15 22:25:16.718 INFO  [main] test,1,ClearAction,executeQuery:UN_KNOW
2025-08-15 22:25:16.718 INFO  [main] test,1,ClearAction,executeQuery:SU
2025-08-15 22:25:16.718 INFO  [main] test,1,ClearAction==>DetailAction
2025-08-15 22:25:16.718 INFO  [main] test,1,DetailAction,execute
2025-08-15 22:25:16.718 INFO  [main] test,1,DetailAction,executeQuery:SU
2025-08-15 22:25:16.718 INFO  [main] test,1,DetailAction==>FinalAction
2025-08-15 22:25:16.718 INFO  [main] test,1,FinalAction,execute
2025-08-15 22:25:16.718 INFO  [main] test,1,FinalAction,executeQuery:UN_KNOW
2025-08-15 22:25:16.718 INFO  [main] test,1,FinalAction,executeQuery:SU
2025-08-15 22:25:16.718 INFO  [main] test,1,FinalAction==>PayAction
2025-08-15 22:25:16.718 INFO  [main] test,1,PayAction,execute
2025-08-15 22:25:16.718 INFO  [main] test,1,PayAction,executeQuery:UN_KNOW
2025-08-15 22:25:16.718 INFO  [main] test,1,PayAction,executeQuery:UN_KNOW
2025-08-15 22:25:16.718 INFO  [main] test,1,PayAction,executeQuery:UN_KNOW
2025-08-15 22:25:16.718 INFO  [main] test,1,PayAction,executeQuery:UN_KNOW
2025-08-15 22:25:16.718 INFO  [main] test,1,PayAction,executeQuery:SU
2025-08-15 22:25:16.902 DEBUG [main] 本次请求处理结束:1,test,{"status":"ING","state":"PayAction","direct":"RIGHT","actionResult":"SU"}
```

## API 文档

### 核心接口

#### SagaManager - 流程管理器

```java
public interface SagaManager {
    
    /**
     * 执行SAGA流程
     * @param flowCode 流程编码
     * @param businessId 业务ID
     * @param event 触发事件
     */
    void execute(String flowCode, Long businessId, SagaEvent event);
    
    /**
     * 查询流程状态
     * @param flowCode 流程编码
     * @param businessId 业务ID
     * @return 流程状态
     */
    SagaStatus getStatus(String flowCode, Long businessId);
    
    /**
     * 手动触发流程继续执行
     * @param flowCode 流程编码
     * @param businessId 业务ID
     */
    void resume(String flowCode, Long businessId);
}
```

#### SagaAction - 业务动作接口

```java
public interface SagaAction {
    
    /**
     * 执行业务逻辑
     * @param context 上下文
     */
    void execute(SagaContext context);
    
    /**
     * 回滚业务逻辑
     * @param context 上下文
     */
    void rollback(SagaContext context);
    
    /**
     * 查询执行状态
     * @param context 上下文
     * @return 执行结果
     */
    ActionResult queryExecuteStatus(SagaContext context);
    
    /**
     * 查询回滚状态
     * @param context 上下文
     * @return 回滚结果
     */
    ActionResult queryRollbackStatus(SagaContext context);
}
```

### 配置参数

| 配置项 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| `saga.session.provider` | String | none | 会话管理器: none/redis |
| `saga.retry.max-attempts` | Integer | 3 | 最大重试次数 |
| `saga.retry.delay` | Duration | 1s | 重试间隔 |
| `saga.timeout.execution` | Duration | 300s | 执行超时时间 |
| `saga.timeout.rollback` | Duration | 60s | 回滚超时时间 |

### 事件类型

```java
public enum SagaEvent {
    START,      // 启动流程
    PUSH,       // 推进流程
    ROLLBACK,   // 回滚流程
    RESUME      // 恢复流程
}
```

### 状态枚举

```java
public enum ActionResult {
    NONE,       // 未执行
    SUCCESS,    // 成功
    FAIL,       // 失败
    UNKNOWN     // 未知状态
}
```

## 许可证

本项目基于 [MIT License](LICENSE) 开源协议。

## 贡献指南

欢迎提交 Issue 和 Pull Request！在提交之前，请确保：

1. 🧪 所有测试通过 `mvn test`
2. 📝 代码符合项目规范 `mvn checkstyle:check`
3. 📚 添加必要的文档说明

## 相关文档

- [📖 流程架构组件说明](./doc/流程架构组件介绍.md)
- [🔧 开发手册](./doc/开发手册.md)
- [🏗️ 架构设计文档](./doc/架构说明.md)
- [⚖️ 事务模式比较](./doc/事务比较.md)

---

<div align="center">
Made with ❤️ by Flow Arch Team
</div>