# elegent-tx 分布式事务框架

**Repository Path**: erickech/elegent-tx

## Basic Information

- **Project Name**: elegent-tx 分布式事务框架
- **Description**: Elegent tx（优雅分布式事务框架）是一款实现了saga模式的分布式事务框架。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2024-12-04
- **Last Updated**: 2024-12-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

![](doc/images/logob.png)

# Elegent tx【优雅分布式事务框架】

## 框架介绍

​	Elegent tx（优雅分布式事务框架）是一款实现了saga模式的分布式事务框架。 这个组件具有的特点：

1. 通过注解的方式为每个微服务的方法开启事务，标注子事务。
2. 通过注解的方式为每个微服务的标记回滚方法，回滚的方法中包括原始方法的参数，以及用户自定义的暂存数据用于回滚。
3. 当某个微服务发生异常，会通知到每个微服务进行回滚逻辑处理。
4. 默认使用redis作为数据中心，用户可以自己扩展数据中心的实现。

下面是Elegent tx框架的系统架构图：

![](doc/images/system.png)



可以通过工作模式图来理解此框架的工作原理，这也是saga模式工作原理。

![](doc/images/6-2.png)

我们的业务方法被elegent-tx管理后，会将自身的状态提交给框架，框架负责记录每个节点的执行情况，当某个节点发生了异常，会通过框架的回滚事务分发处理器向各节点发送回滚通知，各节点收到回滚通知后，会执行回滚方法。



## 使用说明

### 准备工作

（1）在项目中引入依赖

```xml
<dependency>
    <groupId>cn.elegent</groupId>
    <artifactId>elegent-tx</artifactId>
    <version>1.1.0</version>
</dependency>
```
（2）在项目配置文件添加配置，示例如下（同ElegentAC 框架）：

```yaml
elegent:
  ac:
    username: admin
    password: public
    serverURI: tcp://127.0.0.1:1883
    clientId: acpro
    keepAliveInterval: 10
    connectionTimeout: 30
```

注意：必须要有spring.application.name的配置

elegent.ac 配置说明：

| 配置                | 说明                  |
| ----------------- | ------------------- |
| host              | MQ的主机地址             |
| port              | MQ中间件的端口。 EMQ的是1883 |
| username          | 登录用户名               |
| password          | 登录密码                |
| clientId          | 客户端ID               |
| keepAliveInterval | 心跳检测（秒）             |
| connectionTimeout | 连接超时时间              |

（3）启动消息中间件。

### 代码编写

#### 在服务类上添加事务注解

服务的业务代码，示例如下：

```java
@Override
@ElegentTx(mainName = "主事务名称",childName = "子事务名称")
public void save(User user){
    ......
    ElegentACTXContext.setSnapshot("user",user);//保存快照
    ......
}
```

@ElegentTx属性说明：

​	mainName：主事务名称，整个链路的主事务名称相同。

​	childName： 子事务名称，当前子事务名称，不可以重名。

在业务逻辑方法中可以使用ElegentACTXContext的setSnapshot保存快照，之后用于回滚。

```java
ElegentACTXContext.setSnapshot("user",user);//保存快照
```

参数1：快照名称（key）

参数2：快照数据

#### 回滚逻辑的编写

我们需要在异步调用的每个微服务中编写**回滚处理类**，示例代码如下：

```JAVA
@RollBack(mainName = "主事务名称",childName = "子事务名称")
public class RollBackSubA implements RollBackHandler {

    @Override
    public void doRollBack(String topic,Snapshot snapshot) {
        
      	Product product = snapshot.findData("product",Product.class);  //提取快照
    }
}
```

在类上，我们使用@RollBack注解标注此类为回滚处理类，并指定mainName（主事务名称）和childName（子事务名称）。实现此接口的doRollBack方法，接受参数有topic （回滚主题）和snapshot（快照数据）。我们主要是使用快照数据来实现回滚逻辑的。

如果存储的是对象，使用两个参数的方法，指定要返回的class类型

```java
Product product = snapshot.findData( "product",Product.class ); 
```

如果存储的基本数据类型，可以使用一个参数的方法

```java
Integer orderId= snapshot.findData( "orderId"); 
```

## 参与贡献

1.  从 `master` 分支 `checkout` 一个新分支（**注**：*请务必保证 master 代码是最新的*）
2.  新分支命名格式：`docs/username_description`，例如：`docs/tom_新增分布式锁配置项`
3.  在新分支上编辑文档、代码，并提交代码
4.  最后 `PR` 合并到 `develop` 分支，等待作者合并即可