# distributed-transaction

**Repository Path**: packagejava/distributed-transaction

## Basic Information

- **Project Name**: distributed-transaction
- **Description**: 基于本地消息表实现的分布式事务Spring Boot Starter，实现最终一致性事务。
- 零配置集成，引入依赖即可使用
- 基于AOP实现，对业务代码无侵入
- 支持事务重试，确保最终一致性
- 可配置线程池参数，灵活调整性能
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-05-19
- **Last Updated**: 2025-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 分布式事务Spring Boot Starter

基于本地消息表实现的分布式事务Spring Boot Starter，实现最终一致性事务。

## 功能特点

- 零配置集成，引入依赖即可使用
- 基于AOP实现，对业务代码无侵入
- 支持事务重试，确保最终一致性
- 可配置线程池参数，灵活调整性能

## 快速开始

### 1. 添加依赖

```xml
<dependency>
    <groupId>cn.minhx</groupId>
    <artifactId>distributed-transaction-spring-boot-starter</artifactId>
    <version>${version}</version>
</dependency>
```

### 2. 初始化数据库

执行 `distributed-transaction-spring-boot-starter/docs/schema.sql` 文件中的SQL语句，创建分布式事务记录表：

```sql
-- 分布式事务记录表
CREATE TABLE IF NOT EXISTS `transaction_record` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `status` varchar(10) NOT NULL COMMENT '事务状态：PENDING-待处理, SUCCESS-成功, FAILED-失败',
  `priority` int(11) NOT NULL DEFAULT '5' COMMENT '优先级，数值越小优先级越高',
  `retry_count` int(11) NOT NULL DEFAULT '0' COMMENT '已重试次数',
  `max_retry_count` int(11) NOT NULL DEFAULT '3' COMMENT '最大重试次数',
  `retry_interval` int(11) NOT NULL DEFAULT '600' COMMENT '重试间隔（秒）',
  `next_retry_time` datetime NOT NULL COMMENT '下次重试时间',
  `invoke_context` text NOT NULL COMMENT '方法调用上下文信息（JSON格式）',
  `result` text COMMENT '执行结果',
  `error_message` varchar(2000) DEFAULT NULL COMMENT '错误信息',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `deleted` tinyint(1) NOT NULL DEFAULT '0' COMMENT '是否已删除：0-未删除，1-已删除',
  PRIMARY KEY (`id`),
  KEY `idx_status_next_retry_time` (`status`, `next_retry_time`),
  KEY `idx_create_time` (`create_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='分布式事务记录表';
```

### 3. 在方法上添加注解

```java
@Service
public class MyService {

    @DistributedTransaction
    public void someBusinessMethod(int param1, String param2) {
        // 需要重试的业务逻辑...
    }
}
```

### 4. 完成！

不需要任何额外配置，Spring Boot应用会自动加载并启用分布式事务功能。

## 配置选项（可选）

可以在`application.yml`中添加如下配置：

```yaml
# 分布式事务配置
dtm:
  # 是否启用分布式事务（默认为true）
  enabled: true
  
  # 事务重试配置
  retry:
    # 是否启用重试任务（默认为true）
    # 在分布式部署环境中，建议只在一个实例上启用此选项
    enabled: true
    # 扫描任务执行间隔（毫秒）
    scan-interval: 30000
    # 每次扫描的任务数量上限
    batch-size: 100
    
  # 线程池配置
  thread-pool:
    # 核心线程数
    core-pool-size: 5
    # 最大线程数
    max-pool-size: 10
    # 空闲线程存活时间（秒）
    keep-alive-time: 60
    # 队列容量
    queue-capacity: 100
    # 线程名称前缀
    thread-name-prefix: dtm-pool-
```

## 多实例部署注意事项

在分布式部署环境中（多个应用实例），为避免事务重试任务在每个实例上重复执行，建议：

1. 在所有实例上保持分布式事务功能开启（`dtm.enabled=true`）
2. 只在其中一个实例上启用重试任务（`dtm.retry.enabled=true`），其他实例关闭（`dtm.retry.enabled=false`）

```yaml
# 只在一个实例上配置：
dtm:
  retry:
    enabled: true
    
# 其他实例上配置：
dtm:
  retry:
    enabled: false
```

对于生产环境，推荐使用分布式调度框架（如Quartz集群、XXL-Job等）来统一调度事务重试任务，以实现更可靠的任务执行。

## 表结构说明

`transaction_record` 表是分布式事务的核心表，用于记录事务执行状态和重试信息：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint | 主键ID |
| status | varchar(10) | 事务状态：PENDING-待处理, SUCCESS-成功, FAILED-失败 |
| priority | int | 优先级，数值越小优先级越高 |
| retry_count | int | 已重试次数 |
| max_retry_count | int | 最大重试次数 |
| retry_interval | int | 重试间隔（秒） |
| next_retry_time | datetime | 下次重试时间 |
| invoke_context | text | 方法调用上下文信息（JSON格式） |
| result | text | 执行结果 |
| error_message | varchar(2000) | 错误信息 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |
| deleted | tinyint(1) | 是否已删除：0-未删除，1-已删除 |

## 注解参数说明

`@DistributedTransaction`注解参数：

- `maxRetries`: 最大重试次数，默认3次
- `async`: 是否异步执行，默认true
- `timeout`: 任务超时时间(秒)，默认30秒
- `interval`: 重试间隔时间(秒)，默认600秒
- `priority`: 事务处理优先级，数值越小优先级越高，默认5