0
# Seata Spring Boot Starter
1

2
Seata Spring Boot Starter provides automatic configuration and integration of Seata's distributed transaction capabilities into Spring Boot applications. It enables seamless transaction coordination across multiple services and databases with minimal configuration, supporting AT (Automatic Transaction), XA, TCC (Try-Confirm-Cancel), and Saga transaction patterns for 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 to your `pom.xml`:
11

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

20
## Core Dependencies
21

22
The starter automatically includes:
23

24
```xml
25
<!-- Core Seata functionality -->
26
<dependency>
27
    <groupId>io.seata</groupId>
28
    <artifactId>seata-all</artifactId>
29
</dependency>
30

31
<!-- Auto-configuration components -->
32
<dependency>
33
    <groupId>io.seata</groupId>
34
    <artifactId>seata-spring-autoconfigure-client</artifactId>
35
</dependency>
36
```
37

38
## Basic Usage
39

40
### 1. Add Dependency and Configuration
41

42
Add the starter dependency to your Spring Boot project and configure basic properties:
43

44
```properties
45
# Enable Seata (default: true)
46
seata.enabled=true
47

48
# Application configuration
49
seata.application-id=my-application
50
seata.tx-service-group=my-tx-group
51

52
# Registry and config center (example for Nacos)
53
seata.registry.type=nacos
54
seata.registry.nacos.server-addr=127.0.0.1:8848
55
seata.config.type=nacos
56
seata.config.nacos.server-addr=127.0.0.1:8848
57
```
58

59
### 2. Use Global Transactions
60

61
```java
62
import io.seata.spring.annotation.GlobalTransactional;
63
import org.springframework.stereotype.Service;
64

65
@Service
66
public class BusinessService {
67
    
68
    @GlobalTransactional
69
    public void handleBusinessLogic() {
70
        // Your business logic here
71
        // Multiple database operations across different services
72
        // will be coordinated as a distributed transaction
73
        
74
        orderService.createOrder();
75
        accountService.deductBalance();
76
        inventoryService.decreaseStock();
77
    }
78
}
79
```
80

81
### 3. Automatic DataSource Proxying
82

83
DataSources are automatically proxied for AT mode transactions:
84

85
```java
86
@Configuration
87
public class DataSourceConfig {
88
    
89
    @Bean
90
    @Primary
91
    public DataSource dataSource() {
92
        // Your DataSource configuration
93
        // Will be automatically proxied by Seata
94
        return new HikariDataSource();
95
    }
96
}
97
```
98

99
## Architecture
100

101
Seata Spring Boot Starter provides a comprehensive auto-configuration framework built around several key components:
102

103
- **Auto-Configuration Classes**: Four main configuration classes that automatically set up Seata components based on application context and properties
104
- **Global Transaction Scanner**: Scans for `@GlobalTransactional` annotations and manages transaction lifecycle
105
- **DataSource Proxying**: Automatic proxy creation for DataSource beans to enable AT/XA transaction modes
106
- **HTTP Integration**: Request interceptors for transaction context propagation across HTTP calls
107
- **Saga Engine**: State machine-based long-running transaction support with async execution capabilities
108

109
The starter follows Spring Boot's auto-configuration patterns, enabling zero-configuration distributed transactions while providing extensive customization options through properties.
110

111
## Capabilities
112

113
### Core Transaction Management
114

115
Automatic configuration of Seata's global transaction scanning and management capabilities. Provides the foundation for distributed transaction coordination across microservices.
116

117
```java { .api }
118
// Auto-configured beans
119
@ConditionalOnProperty(prefix = "seata", name = "enabled", havingValue = "true", matchIfMissing = true)
120
public class SeataAutoConfiguration {
121
    
122
    @Bean("failureHandler")
123
    public FailureHandler failureHandler();
124
    
125
    @Bean
126
    public static GlobalTransactionScanner globalTransactionScanner(
127
        SeataProperties seataProperties, 
128
        FailureHandler failureHandler,
129
        ConfigurableListableBeanFactory beanFactory,
130
        List<ScannerChecker> scannerCheckers
131
    );
132
}
133
```
134

135
[Core Transaction Management](./core-transaction-management.md)
136

137
### DataSource Auto-Proxying
138

139
Automatic DataSource proxy creation for AT (Automatic Transaction) and XA transaction modes. Enables transparent database transaction management without manual proxy configuration.
140

141
```java { .api }
142
@ConditionalOnBean(DataSource.class)
143
@ConditionalOnExpression("${seata.enabled:true} && ${seata.enableAutoDataSourceProxy:true}")
144
public class SeataDataSourceAutoConfiguration {
145
    
146
    @Bean("seataAutoDataSourceProxyCreator")
147
    public static SeataAutoDataSourceProxyCreator seataAutoDataSourceProxyCreator(
148
        SeataProperties seataProperties
149
    );
150
}
151
```
152

153
[DataSource Auto-Proxying](./datasource-auto-proxying.md)
154

155
### HTTP Transaction Propagation
156

157
HTTP request interceptor configuration for propagating transaction context across web service calls. Supports both javax and Jakarta EE servlet environments.
158

159
```java { .api }
160
@Configuration(proxyBeanMethods = false)
161
@ConditionalOnWebApplication
162
@ConditionalOnMissingBean(SeataWebMvcConfigurer.class)
163
@ConditionalOnProperty(prefix = "seata.client.http", name = "interceptor-enabled", havingValue = "true", matchIfMissing = true)
164
@AutoConfigureOrder(Ordered.LOWEST_PRECEDENCE)
165
public class SeataHttpAutoConfiguration {
166
    
167
    @Bean
168
    @ConditionalOnClass(name = "jakarta.servlet.http.HttpServletRequest")
169
    public JakartaSeataWebMvcConfigurer jakartaSeataWebMvcConfigurer();
170
    
171
    @Bean
172
    @ConditionalOnMissingBean(JakartaSeataWebMvcConfigurer.class)
173
    public SeataWebMvcConfigurer seataWebMvcConfigurer();
174
}
175
```
176

177
[HTTP Transaction Propagation](./http-transaction-propagation.md)
178

179
### Saga Pattern Support
180

181
Auto-configuration for Saga distributed transaction pattern with state machine engine and async execution support. Ideal for long-running business processes and complex workflow coordination.
182

183
```java { .api }
184
@Configuration(proxyBeanMethods = false)
185
@ConditionalOnProperty({"seata.enabled", "seata.saga.enabled"})
186
public class SeataSagaAutoConfiguration {
187
    
188
    @Bean
189
    @ConditionalOnBean(DataSource.class)
190
    @ConditionalOnMissingBean
191
    @ConfigurationProperties("seata.saga.state-machine")
192
    public StateMachineConfig dbStateMachineConfig(
193
        DataSource dataSource,
194
        @Qualifier("seataSagaDataSource") @Autowired(required = false) DataSource sagaDataSource,
195
        @Qualifier("seataSagaAsyncThreadPoolExecutor") @Autowired(required = false) ThreadPoolExecutor threadPoolExecutor,
196
        @Value("${spring.application.name:}") String applicationId,
197
        @Value("${seata.tx-service-group:}") String txServiceGroup
198
    );
199
    
200
    @Bean
201
    @ConditionalOnMissingBean
202
    public StateMachineEngine stateMachineEngine(StateMachineConfig config);
203
}
204
```
205

206
[Saga Pattern Support](./saga-pattern-support.md)
207

208
## Configuration Properties
209

210
### Core Properties (seata.*)
211

212
```java { .api }
213
// Main configuration class
214
@ConfigurationProperties(prefix = "seata")
215
public class SeataProperties {
216
    
217
    // Enable/disable Seata auto-configuration
218
    private boolean enabled = true;
219
    
220
    // Application identifier
221
    private String applicationId;
222
    
223
    // Transaction service group
224
    private String txServiceGroup;
225
    
226
    // DataSource proxy configuration
227
    private boolean enableAutoDataSourceProxy = true;
228
    private String dataSourceProxyMode = "AT";
229
    private boolean useJdkProxy = false;
230
    
231
    // Transaction scanning configuration
232
    private String[] scanPackages = {};
233
    private String[] excludesForScanning = {};
234
    private String[] excludesForAutoProxying = {};
235
    
236
    // Cloud integration
237
    private String accessKey;
238
    private String secretKey;
239
}
240
```
241

242
### Saga Async Thread Pool Properties
243

244
```java { .api }
245
@ConfigurationProperties(prefix = "seata.saga.state-machine.async-thread-pool")
246
public class SagaAsyncThreadPoolProperties {
247
    
248
    // Core thread pool size (default: 1)
249
    private int corePoolSize = 1;
250
    
251
    // Maximum thread pool size (default: 20)
252
    private int maxPoolSize = 20;
253
    
254
    // Thread keep-alive time in seconds (default: 60)
255
    private int keepAliveTime = 60;
256
}
257
```
258

259
## Constants and Bean Names
260

261
```java { .api }
262
// Configuration property prefixes
263
public interface StarterConstants {
264
    String SEATA_PREFIX = "seata";
265
    String CLIENT_PREFIX = "seata.client";
266
    String SAGA_PREFIX = "seata.saga";
267
    String HTTP_PREFIX = "seata.client.http";
268
    String TCC_FENCE_PREFIX = "seata.tcc.fence";
269
    String SAGA_STATE_MACHINE_PREFIX = "seata.saga.state-machine";
270
}
271

272
// Saga configuration bean names (from SeataSagaAutoConfiguration)
273
public static final String SAGA_DATA_SOURCE_BEAN_NAME = "seataSagaDataSource";
274
public static final String SAGA_ASYNC_THREAD_POOL_EXECUTOR_BEAN_NAME = "seataSagaAsyncThreadPoolExecutor";
275
public static final String SAGA_REJECTED_EXECUTION_HANDLER_BEAN_NAME = "seataSagaRejectedExecutionHandler";
276

277
// Auto DataSource Proxy bean name (from SeataDataSourceAutoConfiguration)
278
public static final String BEAN_NAME_SEATA_AUTO_DATA_SOURCE_PROXY_CREATOR = "seataAutoDataSourceProxyCreator";
279

280
// Core component bean names (from SeataAutoConfiguration)
281
public static final String BEAN_NAME_FAILURE_HANDLER = "failureHandler";
282
public static final String BEAN_NAME_SPRING_APPLICATION_CONTEXT_PROVIDER = "springApplicationContextProvider";
283
```