0
# Seata Spring Boot Starter
1

2
Spring Boot starter for Apache Seata distributed transaction solution. This starter enables seamless integration of Seata's distributed transaction capabilities into Spring Boot applications through automatic configuration of Transaction Coordinator (TC), Transaction Manager (TM), and Resource Manager (RM) components. It supports multiple transaction modes including AT, TCC, SAGA, and XA for handling data consistency in distributed microservices architectures.
3

4
## Package Information
5

6
- **Package Name**: seata-spring-boot-starter
7
- **Package Type**: maven
8
- **Group ID**: io.seata
9
- **Language**: Java
10
- **Installation**: Add dependency to `pom.xml`:
11

12
```xml
13
<dependency>
14
    <groupId>io.seata</groupId>
15
    <artifactId>seata-spring-boot-starter</artifactId>
16
    <version>2.0.0</version>
17
</dependency>
18
```
19

20
## Core Imports
21

22
```java
23
// Core imports for using distributed transactions
24
import io.seata.spring.annotation.GlobalTransactional;
25
import io.seata.tm.api.FailureHandler;
26
import io.seata.spring.annotation.GlobalTransactionScanner;
27
import io.seata.spring.annotation.datasource.SeataAutoDataSourceProxyCreator;
28
import io.seata.spring.boot.autoconfigure.properties.SeataProperties;
29
```
30

31
## Basic Usage
32

33
Add the starter dependency and configure your application properties:
34

35
```yaml
36
# application.yml
37
seata:
38
  enabled: true
39
  application-id: my-app
40
  tx-service-group: my-tx-group
41
  enable-auto-data-source-proxy: true
42
  data-source-proxy-mode: AT
43
```
44

45
```java
46
// Application class - no additional configuration needed
47
@SpringBootApplication
48
public class MyApplication {
49
    public static void main(String[] args) {
50
        SpringApplication.run(MyApplication.class, args);
51
    }
52
}
53

54
// Service class with distributed transactions
55
@Service
56
public class OrderService {
57
    
58
    @GlobalTransactional
59
    public void createOrder(Order order) {
60
        // This method will be wrapped in a distributed transaction
61
        orderRepository.save(order);
62
        inventoryService.reduceStock(order.getProductId(), order.getQuantity());
63
        paymentService.processPayment(order.getPaymentInfo());
64
    }
65
}
66
```
67

68
## Architecture
69

70
The starter provides auto-configuration for Seata distributed transaction framework through four main components:
71

72
- **SeataAutoConfiguration**: Core transaction management and failure handling
73
- **SeataDataSourceAutoConfiguration**: Automatic DataSource proxy creation for transaction coordination  
74
- **SeataHttpAutoConfiguration**: Web MVC integration for transaction context propagation
75
- **SeataSagaAutoConfiguration**: State machine engine configuration for SAGA pattern support
76

77
All configurations are conditional and activated based on properties and bean presence, ensuring minimal overhead when features are not used.
78

79
## Capabilities
80

81
### Core Transaction Management
82

83
Provides the foundational distributed transaction capabilities including global transaction scanning and failure handling.
84

85
```java { .api }
86
// Auto-configured beans (managed automatically by Spring Boot)
87
// Required imports for this API section:
88
// import io.seata.spring.annotation.GlobalTransactionScanner;
89
// import io.seata.tm.api.FailureHandler;
90
// import io.seata.spring.annotation.ScannerChecker;
91
// import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
92

93
// Global transaction scanner for detecting @GlobalTransactional annotations
94
static GlobalTransactionScanner globalTransactionScanner(
95
    SeataProperties seataProperties, 
96
    FailureHandler failureHandler,
97
    ConfigurableListableBeanFactory beanFactory,
98
    @Autowired(required = false) List<ScannerChecker> scannerCheckers
99
);
100

101
// Default failure handler for transaction failures
102
FailureHandler failureHandler();
103
```
104

105
**Configuration:**
106
- Enabled when `seata.enabled=true` (default: true)
107
- Automatically scans for `@GlobalTransactional` annotations
108
- Configurable package scanning and exclusions
109

110
### DataSource Auto-Proxying
111

112
Automatically wraps DataSource beans with Seata proxies to enable transaction coordination across multiple databases.
113

114
```java { .api }
115
// Required imports: import io.seata.spring.annotation.datasource.SeataAutoDataSourceProxyCreator;
116

117
// Auto-configured bean for DataSource proxying
118
static SeataAutoDataSourceProxyCreator seataAutoDataSourceProxyCreator(SeataProperties seataProperties);
119
```
120

121
**Configuration:**
122
- Enabled when `seata.enable-auto-data-source-proxy=true` (default: true)
123
- Supports AT, XA, and TCC transaction modes
124
- Configurable exclusions for specific DataSource beans
125

126
### Web Integration
127

128
Provides HTTP request/response interceptor integration for transaction context propagation in web applications.
129

130
```java { .api }
131
// Required imports:
132
// import io.seata.integration.http.JakartaSeataWebMvcConfigurer;
133
// import io.seata.integration.http.SeataWebMvcConfigurer;
134

135
// Auto-configured web MVC configurers (Jakarta EE 9+)
136
JakartaSeataWebMvcConfigurer jakartaSeataWebMvcConfigurer();
137

138
// Auto-configured web MVC configurers (Java EE / Jakarta EE 8)
139
SeataWebMvcConfigurer seataWebMvcConfigurer();
140
```
141

142
**Configuration:**
143
- Enabled for web applications with `seata.client.http.interceptor-enabled=true` (default: true)
144
- Automatically detects Jakarta vs javax servlet APIs
145
- Handles transaction context propagation across HTTP boundaries
146

147
### SAGA Pattern Support
148

149
Configures state machine engine for complex distributed transaction workflows using the SAGA pattern.
150

151
```java { .api }
152
// Required imports:
153
// import io.seata.saga.engine.StateMachineConfig;
154
// import io.seata.saga.engine.StateMachineEngine;
155
// import java.util.concurrent.ThreadPoolExecutor;
156
// import java.util.concurrent.RejectedExecutionHandler;
157
// import javax.sql.DataSource;
158

159
// State machine configuration for SAGA pattern
160
StateMachineConfig dbStateMachineConfig(
161
    DataSource dataSource,
162
    @Qualifier("seataSagaDataSource") @Autowired(required = false) DataSource sagaDataSource,
163
    @Qualifier("seataSagaAsyncThreadPoolExecutor") @Autowired(required = false) ThreadPoolExecutor threadPoolExecutor,
164
    @Value("${spring.application.name:}") String applicationId,
165
    @Value("${seata.tx-service-group:}") String txServiceGroup
166
);
167

168
// State machine engine for executing SAGA workflows
169
StateMachineEngine stateMachineEngine(StateMachineConfig config);
170

171
// Async thread pool for SAGA execution (conditional on enable-async=true)
172
ThreadPoolExecutor sagaAsyncThreadPoolExecutor(
173
    SagaAsyncThreadPoolProperties properties,
174
    RejectedExecutionHandler rejectedExecutionHandler
175
);
176

177
// Rejection handler for async operations
178
RejectedExecutionHandler sagaRejectedExecutionHandler();
179
```
180

181
**Configuration:**
182
- Enabled when both `seata.enabled=true` and `seata.saga.enabled=true`
183
- Async thread pool enabled when `seata.saga.state-machine.enable-async=true`
184
- Configurable thread pool settings via `seata.saga.state-machine.async-thread-pool.*`
185
- Database-backed state machine persistence
186

187
## Configuration Properties
188

189
### Main Configuration (seata.*)
190

191
```java { .api }
192
// import io.seata.spring.boot.autoconfigure.properties.SeataProperties;
193

194
class SeataProperties {
195
    // Enable/disable Seata auto-configuration
196
    boolean enabled = true;
197
    
198
    // Application identifier for transaction coordination
199
    String applicationId;
200
    
201
    // Transaction service group name
202
    String txServiceGroup;
203
    
204
    // Enable automatic DataSource proxy creation
205
    boolean enableAutoDataSourceProxy = true;
206
    
207
    // DataSource proxy mode: AT, XA, TCC
208
    String dataSourceProxyMode = "AT";
209
    
210
    // Use JDK proxy instead of CGLIB
211
    boolean useJdkProxy = false;
212
    
213
    // Packages to scan for @GlobalTransactional annotations
214
    String[] scanPackages = {};
215
    
216
    // Bean names to exclude from transaction scanning
217
    String[] excludesForScanning = {};
218
    
219
    // DataSource bean names to exclude from auto-proxying
220
    String[] excludesForAutoProxying = {};
221
    
222
    // Alibaba Cloud access credentials
223
    String accessKey;
224
    String secretKey;
225
}
226
```
227

228
### SAGA Thread Pool Configuration (seata.saga.state-machine.async-thread-pool.*)
229

230
```java { .api }
231
// import io.seata.spring.boot.autoconfigure.properties.SagaAsyncThreadPoolProperties;
232

233
class SagaAsyncThreadPoolProperties {
234
    // Core pool size for async operations
235
    int corePoolSize = 1;
236
    
237
    // Maximum pool size
238
    int maxPoolSize = 20;
239
    
240
    // Keep alive time in seconds
241
    int keepAliveTime = 60;
242
}
243
```
244

245
### Spring Cloud Alibaba Integration (spring.cloud.alibaba.seata.*)
246

247
```java { .api }
248
// import io.seata.spring.boot.autoconfigure.properties.SpringCloudAlibabaConfiguration;
249

250
class SpringCloudAlibabaConfiguration {
251
    // Application ID (defaults to spring.application.name)
252
    String applicationId;
253
    
254
    // Transaction service group
255
    String txServiceGroup;
256
}
257
```
258

259
## Constants and Bean Names
260

261
```java { .api }
262
// import io.seata.spring.boot.autoconfigure.StarterConstants;
263

264
// Configuration property prefixes
265
interface StarterConstants {
266
    String SEATA_PREFIX = "seata";
267
    String SEATA_SPRING_CLOUD_ALIBABA_PREFIX = "spring.cloud.alibaba.seata";
268
    String SAGA_PREFIX = "seata.saga";
269
    String SAGA_STATE_MACHINE_PREFIX = "seata.saga.state-machine";
270
    String SAGA_ASYNC_THREAD_POOL_PREFIX = "seata.saga.state-machine.async-thread-pool";
271
    String CLIENT_PREFIX = "seata.client";
272
    String HTTP_PREFIX = "seata.client.http";
273
}
274

275
// Pre-defined bean names for SAGA components (from SeataSagaAutoConfiguration)
276
interface SagaBeanConstants {
277
    String SAGA_DATA_SOURCE_BEAN_NAME = "seataSagaDataSource";
278
    String SAGA_ASYNC_THREAD_POOL_EXECUTOR_BEAN_NAME = "seataSagaAsyncThreadPoolExecutor";
279
    String SAGA_REJECTED_EXECUTION_HANDLER_BEAN_NAME = "seataSagaRejectedExecutionHandler";
280
}
281
```
282

283
## Transaction Modes
284

285
The starter supports multiple distributed transaction modes:
286

287
- **AT Mode**: Automatic compensation based on SQL parsing and reverse SQL generation
288
- **TCC Mode**: Try-Confirm-Cancel pattern with manual compensation
289
- **SAGA Mode**: State machine-based long transaction pattern  
290
- **XA Mode**: Traditional two-phase commit protocol for XA-compliant resources
291

292
## Error Handling
293

294
The starter provides automatic failure handling through:
295

296
- `DefaultFailureHandlerImpl`: Default implementation for transaction failures
297
- Configurable timeout and retry policies
298
- Integration with Spring Boot's error handling mechanisms
299
- Detailed logging for transaction coordination issues
300

301
Configure custom failure handling by providing your own `FailureHandler` bean:
302

303
```java
304
@Configuration
305
public class SeataConfig {
306
    
307
    @Bean
308
    @Primary
309
    public FailureHandler customFailureHandler() {
310
        return new CustomFailureHandlerImpl();
311
    }
312
}
313
```