Appearance
Seata
本文以Seata为例,演示分布式事务实践案例。
1. 介绍
Seata是开源的分布式事务解决方案,Seata为用户提供了AT、TCC、SAGA和XA四种事务模型,为用户打造一站式分布式解决方案。
官网地址:https://seata.apache.org/
在Seata分布式事务解决方案中,有以下角色:
- TC(Transaction Coordinator):事务协调者,维护分布式事务和分支事务的状态,驱动分布式事务提交或回滚;
- TM(Transaction Manager):事务管理者,定义分布式事务边界:开启分布式事务、提交/回滚分布式事务;
- RM(Resource Manager):资源管理者,管理分支事务涉及的资源,与TC交互用于注册分支事务、报告分支事务状态,以及驱动分支事务提交或回滚;
在以上的概念中,分支事务可以理解为本地事务。
2. 运行TC
TC(事务协调者)是作为单独的服务运行的,下载路径:https://seata.apache.org/download/seata-server,选择二进制发行版:

TC有三种存储模式:
- file:默认模式,将分布式事务信息保存在内存中,并持久化到本地文件中,性能较高;
- db:将分布式事务信息保存在数据库中,涉及数据库往返开销,效率较低,但是可用性高;
- redis:将分布式事务信息保存到redis中,效率较高,但是有丢数据的风险;
本次演示基于file模式。解压下载后的二进制文件后,进入seata-server目录,运行以下命令即可启动:
sh
sh ./bin/seata-server.sh如果要关闭seata-server,可以先查出PID:
bashjps -lv | grep -i seata然后关闭进程:
bashkill [pid]
当启动seata-server后,会在本地启动服务端,可以通过以下参数修改启动配置:
-h:指定对外公布的 IP,供客户端发现、访问;-p:指定事务通信端口,客户端通过这个端口连接,默认8091;-m:指定 Seata Server 的事务状态、分支、锁等信息如何存储,可选值为file、db、redis,默认值为file;
例如:
sh
sh ./bin/seata-server.sh -h 127.0.0.1 -p 8091 -m file3. 分布式事务方案实践
当启动了seata-server后,我们就可以在项目中引入seata,完成分布式事务了。
3.1 案例概述
案例模拟下单扣减库存场景,分为订单服务order-service和库存服务stock-service,订单服务通过openfeign远程调用库存服务进行扣减,订单服务和库存服务有各自的数据库。
服务框架参考:https://github.com/Lee-0o0/seata-demo/tree/init
之后,我们可以引入seata依赖,首先在父pom.xml中进行依赖管理:
xml
<properties>
<spring-cloud-alibaba.version>2025.1.0.0</spring-cloud-alibaba.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-alibaba-dependencies</artifactId>
<version>${spring-cloud-alibaba.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>然后分别在order-service和stock-service的pom.xml中引入依赖:
xml
<dependencies>
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-seata</artifactId>
</dependency>
</dependencies>通过引入spring-cloud-starter-alibaba-seata,它可以和openfeign继承,用于传播分布式事务。
之后,可以在order-service和stock-service的配置文件application.yml中添加配置:
yaml
seata:
application-id: ${spring.application.name}
tx-service-group: seata_demo_tx_group
config:
type: file
registry:
type: file
service:
vgroup-mapping:
seata_demo_tx_group: default
grouplist:
default: ${SEATA_SERVER_ADDR:127.0.0.1:8091}application-id:应用标识,取spring.application.name,因此两个服务分别是order-service、stock-service;tx-service-group:应用使用的逻辑事务分组,用于查找对应的协调器(TC)集群;config.type: file:使用本地配置方式,不连接 Nacos 等远程配置中心。这里相关配置直接写在application.yaml中即可;registry.type: file:使用静态地址列表发现 Seata Server,不连接注册中心;service.vgroup-mapping:将逻辑事务分组seata_demo_tx_group映射到名为default的协调器集群;service.grouplist.default:指定default集群的 Seata Server 地址。优先取环境变量SEATA_SERVER_ADDR,未设置则使用127.0.0.1:8091;
在seata中,寻找协调器的路径如下:
txt
tx-service-group:seata_demo_tx_group
↓ vgroup-mapping
协调器集群 default
↓ grouplist
127.0.0.1:8091default 是配置中自行约定的集群名称,关键是映射值与 grouplist 的键保持一致。
3.2 XA模式
XA模式要求资源(例如MySQL)支持XA协议。
首先在order-service和stock-service的配置文件中开启seata,并且设置分布式事务模式:
yaml
seata:
enabled: true
enable-auto-data-source-proxy: true
data-source-proxy-mode: XA
enable-auto-data-source-proxy表示自动进行数据源代理,如果关闭,则需要手动代理数据源,在XA模式下,创建代理数据源如下:javapublic class DataSourceProxy { @Bean("dataSourceProxy") public DataSource dataSource(DruidDataSource druidDataSource) { // DataSourceProxyXA for XA mode return new DataSourceProxyXA(druidDataSource); } }注意,这里的
DruidDataSource是原始数据源,如果是其他的数据源,例如HikariDataSource,需要进行替换。
然后,在下单接口上增加注解@GlobalTransactional:
java
@GlobalTransactional(name = "create-order", rollbackFor = Exception.class, timeoutMills = 30000)
@Transactional
public PurchaseOrder create(Long userId, Long productId, Integer quantity, Boolean exception) {
if (userId == null || userId <= 0 || productId == null || productId <= 0
|| quantity == null || quantity <= 0) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "用户 ID、商品 ID 和数量必须大于 0");
}
PurchaseOrder order = new PurchaseOrder();
order.setUserId(userId);
order.setProductId(productId);
order.setQuantity(quantity);
order.setCreatedAt(LocalDateTime.now().withNano(0));
mapper.insert(order);
// SCA 通过 Feign 传播 XID,订单与库存作为 XA 分支统一提交或回滚。
stockClient.deduct(productId, quantity);
if (exception){
throw new RuntimeException("模拟下单异常,检查库存是否回滚");
}
return order;
}同时使用
@GlobalTransactional和@Transactional的主要目的,是将多条本地 SQL 合并为一个原子操作,并作为一个分支事务参与 Seata 的全局事务。参考资料2。
在IDEA中创建requests.http文件,执行下单请求:
http
@stockUrl = http://localhost:8081
@orderUrl = http://localhost:8082
### 查询库存
GET {{stockUrl}}/stocks/1
### 创建订单:预期 201,并扣减一件库存
POST {{orderUrl}}/orders
Content-Type: application/json
{
"userId": 1,
"productId": 1,
"quantity": 1,
"exception": true
}stock-service日志如下:
txt
2026-10-31T15:55:29.327+08:00 INFO 74244 --- [stock-service] [nio-8081-exec-7] o.a.seata.rm.AbstractResourceManager : branch register success, xid:172.23.0.4:8091:523257214242091045, branchId:523257214242091047, lockKeys:null
2026-10-31T15:55:29.357+08:00 INFO 74244 --- [stock-service] [h_RMROLE_1_7_16] o.a.s.c.r.p.c.RmBranchRollbackProcessor : rm handle branch rollback process:BranchRollbackRequest{xid='172.23.0.4:8091:523257214242091045', branchId=523257214242091047, branchType=XA, resourceId='jdbc:mysql://127.0.0.1:3307/stock_db', applicationData='null'}
2026-10-31T15:55:29.357+08:00 INFO 74244 --- [stock-service] [h_RMROLE_1_7_16] org.apache.seata.rm.AbstractRMHandler : Branch Rollbacking: 172.23.0.4:8091:523257214242091045 523257214242091047 jdbc:mysql://127.0.0.1:3307/stock_db
2026-10-31T15:55:29.359+08:00 INFO 74244 --- [stock-service] [h_RMROLE_1_7_16] o.a.s.r.datasource.xa.ResourceManagerXA : 172.23.0.4:8091:523257214242091045-523257214242091047 was rollbacked
2026-10-31T15:55:29.359+08:00 INFO 74244 --- [stock-service] [h_RMROLE_1_7_16] org.apache.seata.rm.AbstractRMHandler : Branch Rollbacked result: PhaseTwo_Rollbacked由于exception为true,RM(也就是@GlobalTransactional的服务)发出回滚全局事务的请求,之后RC回滚分支事务。
检查库存,发现也没有减少。
3.3 AT模式
AT分布式事务模式是由Seata提出的创新方案,同样分为两个阶段:
- 阶段一:在本地事务方案中,执行业务逻辑,并且在业务数据库中插入对应的回滚日志;
- 阶段二:
- 如果提交分布式事务,则什么也不用做,非常快;
- 如果是回滚分布式事务,则通过回滚日志,完成回滚;
如果要使用AT模式,需要满足以下要求:
- 数据库支持本地 ACID 事务,可以不用实现XA协议;
- Java程序通过JDBC访问数据库;
因此,在AT模式下,首先需要在业务数据库中创建回滚日志表:https://github.com/apache/incubator-seata/blob/v2.5.0/script/client/at/db/mysql.sql
sql
-- for AT mode you must to init this sql for you business database. the seata server not need it.
CREATE TABLE IF NOT EXISTS `undo_log`
(
`branch_id` BIGINT NOT NULL COMMENT 'branch transaction id',
`xid` VARCHAR(128) NOT NULL COMMENT 'global transaction id',
`context` VARCHAR(128) NOT NULL COMMENT 'undo_log context,such as serialization',
`rollback_info` LONGBLOB NOT NULL COMMENT 'rollback info',
`log_status` INT(11) NOT NULL COMMENT '0:normal status,1:defense status',
`log_created` DATETIME(6) NOT NULL COMMENT 'create datetime',
`log_modified` DATETIME(6) NOT NULL COMMENT 'modify datetime',
UNIQUE KEY `ux_undo_log` (`xid`, `branch_id`)
) ENGINE = InnoDB AUTO_INCREMENT = 1 DEFAULT CHARSET = utf8mb4 COMMENT ='AT transaction mode undo table';
ALTER TABLE `undo_log` ADD INDEX `ix_log_created` (`log_created`);之后,调整配置文件中的分布式事务模式:
yaml
seata:
data-source-proxy-mode: AT同样地,通过exception参数在扣减库存后触发异常,库存服务日志如下:
txt
2026-10-31T16:36:44.523+08:00 INFO 76732 --- [stock-service] [nio-8081-exec-4] o.a.seata.rm.AbstractResourceManager : branch register success, xid:172.23.0.4:8091:523257214242091061, branchId:523257214242091062, lockKeys:stock:1
2026-10-31T16:36:44.535+08:00 INFO 76732 --- [stock-service] [h_RMROLE_1_2_16] o.a.s.c.r.p.c.RmBranchRollbackProcessor : rm handle branch rollback process:BranchRollbackRequest{xid='172.23.0.4:8091:523257214242091061', branchId=523257214242091062, branchType=AT, resourceId='jdbc:mysql://127.0.0.1:3307/stock_db', applicationData='{"autoCommit":false}'}
2026-10-31T16:36:44.535+08:00 INFO 76732 --- [stock-service] [h_RMROLE_1_2_16] org.apache.seata.rm.AbstractRMHandler : Branch Rollbacking: 172.23.0.4:8091:523257214242091061 523257214242091062 jdbc:mysql://127.0.0.1:3307/stock_db
2026-10-31T16:36:44.591+08:00 INFO 76732 --- [stock-service] [h_RMROLE_1_2_16] o.a.s.r.d.undo.AbstractUndoLogManager : xid 172.23.0.4:8091:523257214242091061 branch 523257214242091062, undo_log deleted with GlobalFinished
2026-10-31T16:36:44.591+08:00 INFO 76732 --- [stock-service] [h_RMROLE_1_2_16] o.a.s.rm.datasource.DataSourceManager : branch rollback success, xid:172.23.0.4:8091:523257214242091061, branchId:523257214242091062
2026-10-31T16:36:44.591+08:00 INFO 76732 --- [stock-service] [h_RMROLE_1_2_16] org.apache.seata.rm.AbstractRMHandler : Branch Rollbacked result: PhaseTwo_Rollbacked可以看到正常回滚,库存正常。
3.4 TCC模式
在TCC模式案例下,我们增加一个账户服务account-service,用于保存用户余额。当用户创建订单时,需要扣除余额。
TCC模式就是在程序中,通过代码设定三个接口:
- Try:相当于XA中的
XA PREPARE,用于预占资源; - Confirm:提交本地事务;
- Cancel:回滚本地事务;
在上述的案例中,Try用于冻结用户余额,Confirm用于扣减冻结的余额,Cancel用于取消冻结。
在account-service中定义TCC接口:
java
@LocalTCC
public interface AccountTccAction {
@TwoPhaseBusinessAction(name = "accountFreeze", commitMethod = "confirm",
rollbackMethod = "cancel", useTCCFence = true)
boolean freeze(BusinessActionContext context,
@BusinessActionContextParameter(paramName = "orderId") long orderId,
@BusinessActionContextParameter(paramName = "userId") long userId,
@BusinessActionContextParameter(paramName = "amount") BigDecimal amount);
boolean confirm(BusinessActionContext context);
boolean cancel(BusinessActionContext context);
}@LocalTCC:让 Seata 找到“哪个 Bean 提供 TCC 操作”,并建立方法拦截和回调关系。支持把@LocalTCC标在接口或实现类上;@TwoPhaseBusinessAction:定义在方法上,用于指定TCC具体的confirm和cancel方法;useTCCFence:开启 Seata 的 TCC 防护机制,通过tcc_fence_log表解决三个问题:幂等、空回滚、防悬挂;
BusinessActionContext:是 Seata 为一个 TCC 分支提供的上下文对象,主要保存两类信息:- 事务身份:这是谁的全局事务、哪个分支。
- 业务参数:后续 Confirm、Cancel 需要用到的数据。
当调用Try方法时,会将事务身份、业务参数封装发送给TC,二阶段调用Confirm/Cancel方法时,TC会把这些参数传递过来,RM可以根据这些参数进行提交或回滚。
@BusinessActionContextParameter:用于在Try方法中标记需要由 Seata 保存、供二阶段使用的业务参数;
之后,正常实现以上接口:
java
@Service
public class AccountTccActionImpl implements AccountTccAction {
private final AccountMapper mapper;
public AccountTccActionImpl(AccountMapper mapper) { this.mapper = mapper; }
@Override
@Transactional(rollbackFor = Exception.class)
public boolean freeze(BusinessActionContext context, long orderId, long userId, BigDecimal amount) {
if (context == null || context.getXid() == null || context.getBranchId() <= 0) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "账户扣款必须在全局事务中调用");
}
if (orderId <= 0 || userId <= 0 || amount == null || amount.signum() <= 0
|| amount.scale() > 2 || amount.precision() > 19) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "订单、用户或金额不合法");
}
if (mapper.freeze(userId, amount) != 1) {
throw new ResponseStatusException(HttpStatus.CONFLICT, "账户不存在或可用余额不足");
}
mapper.insert(new Freeze(context.getXid(), context.getBranchId(), orderId, userId, amount, "TRIED"));
return true;
}
@Override
@Transactional(rollbackFor = Exception.class)
public boolean confirm(BusinessActionContext context) { return finish(context, true); }
@Override
@Transactional(rollbackFor = Exception.class)
public boolean cancel(BusinessActionContext context) { return finish(context, false); }
private boolean finish(BusinessActionContext context, boolean commit) {
Freeze freeze = mapper.lock(context.getXid(), context.getBranchId());
// Try 本地事务失败时可能没有冻结记录;Cancel 无需操作余额。
if (freeze == null) { return !commit; }
String target = commit ? "CONFIRMED" : "CANCELLED";
if (target.equals(freeze.status())) { return true; }
if (!"TRIED".equals(freeze.status())) { return false; }
int changed = commit ? mapper.confirm(freeze.userId(), freeze.amount())
: mapper.cancel(freeze.userId(), freeze.amount());
if (changed != 1 || mapper.finish(freeze.xid(), freeze.branchId(), target) != 1) {
throw new IllegalStateException("冻结记录与账户余额不一致,需要重试或排查");
}
return true;
}
}在Controller中调用freeze方法:
java
@RestController
@RequestMapping("/accounts")
public class AccountController {
private final AccountTccAction action;
private final AccountMapper mapper;
public AccountController(AccountTccAction action, AccountMapper mapper) {
this.action = action; this.mapper = mapper;
}
@PostMapping("/debit")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void debit(@RequestBody DebitRequest request) {
if (!RootContext.inGlobalTransaction()) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "缺少全局事务 XID");
}
if (!action.freeze(null, request.orderId(), request.userId(), request.amount())) {
throw new ResponseStatusException(HttpStatus.CONFLICT, "账户冻结失败");
}
}
public record DebitRequest(long orderId, long userId, BigDecimal amount) {}
}在order-service中,通过OpenFeign调用:
java
@GlobalTransactional(name = "create-order", rollbackFor = Exception.class, timeoutMills = 30000)
@Transactional
public PurchaseOrder create(Long userId, Long productId, Integer quantity, Boolean exception) {
if (userId == null || userId <= 0 || productId == null || productId <= 0
|| quantity == null || quantity <= 0) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "用户 ID、商品 ID 和数量必须大于 0");
}
BigDecimal price = productMapper.price(productId);
if (price == null) {
throw new ResponseStatusException(HttpStatus.NOT_FOUND, "商品不存在");
}
PurchaseOrder order = new PurchaseOrder();
order.setUnitPrice(price);
BigDecimal totalAmount = price.multiply(BigDecimal.valueOf(quantity));
if (totalAmount.precision() > 19) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "订单总金额超出允许范围");
}
order.setTotalAmount(totalAmount);
order.setUserId(userId);
order.setProductId(productId);
order.setQuantity(quantity);
order.setCreatedAt(LocalDateTime.now().withNano(0));
mapper.insert(order);
// SCA 通过 Feign 传播 XID,订单与库存作为 AT 分支由全局事务统一协调。
stockClient.deduct(productId, quantity);
// HTTP 入口在账户服务内调用本地 TCC Bean;这里只触发 Try。
accountClient.debit(order.getId(), userId, order.getTotalAmount());
if (Boolean.TRUE.equals(exception)) {
throw new RuntimeException("模拟下单异常,检查订单、库存与账户是否回滚");
}
return order;
}3.5 SAGA模式
SAGA模式适用于长事务,或者涉及第三方服务,无法提供TCC三个接口的情况。
SAGA模式的思想是先直接完成并提交本地事务,如果失败再通过补偿接口回滚。
实现SAGA模式分为编排式和协同式,Seata提供了编排式的实现方案。在Seata中,主要是通过状态机来实现SAGA的。
3.5.1 状态机定义
Seata的状态机是通过json来定义的,语法如下:
java
{
"Name": "reduceInventoryAndBalance",
"Comment": "reduce inventory then reduce balance in a transaction",
"StartState": "ReduceInventory",
"Version": "0.0.1",
"States": {
},
"IsRetryPersistModeUpdate": false,
"IsCompensatePersistModeUpdate": false
}Name:定义状态机的名称,必须唯一;Comment:状态机的描述;Version:状态机的版本;StartState:起始的状态,进行最开始的执行;States:状态列表,通过map的形式定义,其中key是状态名称,在当前状态机下状态名称必须唯一,value是json对象,定义了当前状态下的属性;IsRetryPersistModeUpdate:控制正向执行失败后重新执行时,日志是更新旧记录还是新增记录,默认值为false,表示新增日志;例如,
java创建订单 → 扣减库存 → 事务成功 ↓ 执行失败 ↓ 正向重试当扣减库存失败,需要重新执行正向流程(扣减库存)时:
配置 日志处理 结果 false(默认)INSERT 新日志 保留每次执行的记录 trueUPDATE 上次失败日志 更新原有记录的执行结果 IsCompensatePersistModeUpdate:控制反向补偿失败后重新补偿时,日志是更新旧记录还是新增记录,默认值为false,表示新增日志;
在Seata中,定义了不同的状态类型,通过Type字段定义,具体有:
| Type | 作用 |
|---|---|
ServiceTask | 调用业务服务方法 |
Choice | 根据条件选择下一个节点 |
Succeed | 正常结束状态机 |
Fail | 异常结束状态机 |
CompensationTrigger | 触发 Saga 反向补偿 |
SubStateMachine | 调用另一个状态机 |
CompensateSubMachine | 补偿子状态机 |
ScriptTask | 执行脚本任务 |
LoopStart | 循环任务的起始节点 |
TIP
这些状态可以理解为要执行的一段逻辑。
如果Type类型为ServiceTask,状态的具体属性如下:
java
"States": {
...
"ReduceBalance": {
"Type": "ServiceTask",
"ServiceName": "balanceAction",
"ServiceMethod": "reduce",
"CompensateState": "CompensateReduceBalance",
"IsForUpdate": true,
"IsPersist": true,
"IsAsync": false,
"IsRetryPersistModeUpdate": false,
"IsCompensatePersistModeUpdate": false,
"Loop": {
"Parallel": 3,
"Collection": "$.[collection]",
"ElementVariableName": "element",
"ElementIndexName": "loopCounter",
"CompletionCondition": "[nrOfCompletedInstances] / [nrOfInstances] >= 0.6"
},
"Input": [
"$.[businessKey]",
"$.[amount]",
{
"loopCounter": "$.[loopCounter]",
"element": "$.[element]",
"throwException" : "$.[mockReduceBalanceFail]"
}
],
"Output": {
"compensateReduceBalanceResult": "$.#root"
},
"Status": {
"#root == true": "SU",
"#root == false": "FA",
"$Exception{java.lang.Throwable}": "UN"
},
"Retry": [
{
"Exceptions": ["io.seata.saga.engine.mock.DemoException"],
"IntervalSeconds": 1.5,
"MaxAttempts": 3,
"BackoffRate": 1.5
},
{
"IntervalSeconds": 1,
"MaxAttempts": 3,
"BackoffRate": 1.5
}
],
"Catch": [
{
"Exceptions": [
"java.lang.Throwable"
],
"Next": "CompensationTrigger"
}
],
"Next": "Succeed"
}
...
}ServiceName:服务名称,通常是Bean名称;ServiceMethod:服务方法名称;CompensateState:当前状态的补偿状态;IsForUpdate:标记当前状态是否会修改数据,默认值为false,如果配置了CompensateState,那默认值为true;IsPersist:标志该状态的执行日志是否需要保存,默认值为true;IsAsync:表示是否要异步执行该状态(方法);注意,异步执行的方法会忽略返回值,因此,方法执行结果状态映射(由下文的Status属性定义)会被忽略。异步执行方法默认结果为成功,除非提交异步执行失败(例如线程池满);IsRetryPersistModeUpdate:控制正向执行失败后重新执行时,日志是更新旧记录还是新增记录,默认值为false,表示新增日志;IsCompensatePersistModeUpdate:控制反向执行失败后重新执行时,日志是更新旧记录还是新增记录,默认值为false,表示新增日志;Input:用于定义调用业务方法时传入的参数列表,具有如下特征:Input是一个数组,数组元素与 Java 方法参数按位置一一对应;- 可以通过
$.[变量名]从状态机上下文(StateMachine Context)获取参数; - 支持基本类型、对象、Map、List 等复杂参数;
Seata 使用 Spring Expression Language(SpEL)进行表达式求值。其中,
$是 Seata 状态机定义中的表达式标记,用于表示后面的内容需要解析,而不是直接作为字符串传递。在以上示例中,参数及解释如下:
参数位置 表达式 含义 第一个 $.[businessKey]从状态机上下文获取 businessKey第二个 $.[amount]从状态机上下文获取 amount第三个 {...}构建一个包含三个字段的对象或 Map 假设状态机上下文包含:
javaMap<String, Object> context = new HashMap<>(); context.put("businessKey", "ORDER_1001"); context.put("amount", 100); context.put("loopCounter", 2); context.put("element", "ITEM_001"); context.put("mockReduceBalanceFail", false);那么上述
Input求值后的参数列表相当于:json[ "ORDER_1001", 100, { "loopCounter": 2, "element": "ITEM_001", "throwException": false } ]对应的业务方法可以定义为:
java@Component("balanceAction") public class BalanceAction { public boolean reduce( String businessKey, Integer amount, Map<String, Object> params) { System.out.println(businessKey); System.out.println(amount); System.out.println(params); return true; } }执行时相当于:
javabalanceAction.reduce( "ORDER_1001", 100, Map.of( "loopCounter", 2, "element", "ITEM_001", "throwException", false ) );注意,第三个参数中的
loopCounter、element、throwException是自定义定义的 Map 键名,并非 Seata 固定要求的字段。状态机上下文的数据主要有两个来源:
第一种:启动状态机时传入
javaMap<String, Object> context = new HashMap<>(); context.put("businessKey", "ORDER_1001"); context.put("amount", 100); stateMachineEngine.startWithBusinessKey( "orderSaga", null, "ORDER_1001", context );通过启动参数传入的
context,可以被后续节点的Input表达式读取。第二种:前面节点的 Output 写入
java"ReduceInventory": { "Type": "ServiceTask", "ServiceName": "inventoryAction", "ServiceMethod": "reduce", "Input": [ "$.[businessKey]" ], "Output": { "inventoryResult": "$.#root" }, "Next": "ReduceBalance" }这里的
Output会把reduce()的返回值放入状态机上下文,变量名为inventoryResult。后续节点可以通过:
json"Input": [ "$.[inventoryResult]" ]获取前一个节点的执行结果。
Output:用于将当前业务方法的返回值映射到状态机上下文(StateMachine Context)中,供后续 State 使用,是json对象,其中key就是放入状态机上下文的key,value取自当前方法的返回值;例如:部分 含义 reduceInventoryResult写入状态机上下文的变量名 $标记需要解析的表达式 #root表示业务方法的整个返回值 如果方法返回值是对象:
javaOrderResult { orderId = 1001, status = "SUCCESS" }那以下写法表示将整个对象放入状态机上下文:
json"Output": { "orderResult": "$.#root" }之后可以通过以下表达式获取对象属性:
java"Input": [ "$.[orderResult].orderId" ]以下写法是获取对象具体的属性放入状态机上下文:
json"Output": { "orderId": "$.#root.orderId", "orderStatus": "$.#root.status" }之后节点可以直接使用:
json"Input": [ "$.[orderId]", "$.[orderStatus]" ]Status:节点执行结果映射,会把节点执行结果映射到三种状态:SU(Success)、FA(Fail)、UN(Unknown);Status是map结构,key是条件表达式,value是状态,表示执行结果满足该条件即对应某种状态,以$Exception{开头的表达式表示某种异常;Next:表示该节点执行完成后,下一个要执行的节点;TIP
注意,只有
Status为SU或FA时,才会执行Next定义的下一节点,所以,我们需要在Next节点中判断。一般情况下,
Next节点需要判断上一节点的结果,执行不同节点,所以Next节点类型为Choice:json"ReduceInventory": { "Type": "ServiceTask", "ServiceName": "inventoryAction", "ServiceMethod": "reduce", "Output": { "reduceInventoryResult": "$.#root" }, "Status": { "#root == true": "SU", "#root == false": "FA", "$Exception{java.lang.Throwable}": "UN" }, "Next": "ChoiceState" }, "ChoiceState": { "Type": "Choice", "Choices": [ { "Expression": "[reduceInventoryResult] == true", "Next": "ReduceBalance" } ], "Default": "Fail" }Catch:定义发生匹配异常后的后继节点,例如:json{ "Type": "ServiceTask", "ServiceName": "inventoryService", "ServiceMethod": "reduce", "Status": { "#root == true": "SU", "#root == false": "FA", "$Exception{java.lang.Throwable}": "UN" }, "Catch": [ { "Exceptions": [ "java.lang.IllegalArgumentException" ], "Next": "CompensationTrigger" } ], "Next": "NextState" }表示抛出了
java.lang.IllegalArgumentException,会触发CompensationTrigger节点,该节点的执行结果为UN;而如果抛出了
NullPointerException,由于Catch中没有匹配的异常,不会路由到下一个节点,此时整个状态机流程结束,此时该节点的执行结果为UN。整个状态机结果为FA或UN,可以通过相应的恢复机制重新推进事务或执行补偿,但这不等于异常发生时就自动进入补偿节点。也就是说,当发生异常后:
异常且匹配
Catch:按Catch.Next路由到下一节点;异常但不匹配
Catch:进入异常终止处理,不自动触发补偿;
Retry:定义发生异常时的重试策略,Retry是数组,可以定义多条规则,每条规则的属性如下:属性 含义 Exceptions匹配需要重试的异常类型 IntervalSeconds初始重试间隔,单位为秒 MaxAttempts当前规则允许的最大重试次数,不包含首次调用 BackoffRate调整后续重试等待时间的系数 Exceptions可以不配置,此时框架默认匹配网络异常,而不是所有异常。如果定义了多条规则,在触发规则1的重试处理中,又发生了异常触发重试规则2,此时会重新匹配规则2的重试策略,但都不会超过每个规则的重试次数,并且只要重试成功都会退出重试。
假设同时配置了
Retry、Catch和Status,如果发生异常,会先根据重试策略进行重试,最后再根据重试结果进行Catch匹配和Status映射。Loop:批量执行同一个 Saga 业务节点,略过;
类型为Choice的状态节点,用于选择不同的下一个节点,例如:
json
"ChoiceState":{
"Type": "Choice",
"Choices":[
{
"Expression":"[reduceInventoryResult] == true",
"Next":"ReduceBalance"
}
],
"Default":"Fail"
}Choices:条件分支数组,可以配置多个判断条件,只要满足第一个条件,就会进入该分支,每个条件中,定义了两个属性:Expression:使用 SpEL 表达式判断条件是否成立;注意,Seata Saga 并没有统一要求所有表达式都以
$开头。Input、Output等参数映射属性使用$标记动态取值,而Choice.Expression本身就是 SpEL 表达式,因此直接写[变量名]即可。Next:当前条件成立时执行的下一个节点;
Default:没有任何条件成立时执行的节点;
类型为Succeed的状态节点,标记整个状态机正常结束,但是,正常结束不代表成功,需要每个状态节点都成功才代表成功,示例如下:
json
"Succeed": {
"Type":"Succeed"
}类型为Fail的状态节点,标记整个状态机异常结束:
json
"Fail": {
"Type":"Fail",
"ErrorCode": "PURCHASE_FAILED",
"Message": "purchase failed"
}ErrorCode:错误码;Message:错误消息;
错误码和错误消息会返回给调用者,可以通过 StateMachineInstance.getEndParams() 获取(下一节介绍)。
TIP
Fail 节点不会自动触发反向补偿
类型为CompensationTrigger的状态节点,会触发反向补偿流程:
json
"CompensationTrigger": {
"Type": "CompensationTrigger",
"Next": "Fail"
}触发反向补偿后,Seata 会根据正向节点的实际执行记录,筛选出状态为 SU 或 UN、尚未补偿成功且具备补偿定义的节点,执行对应的补偿方法;明确为 FA 的节点一般不会参与补偿。
这里最值得关注的是 UN:它意味着业务结果不确定,所以补偿方法不仅要幂等,还必须能处理正向操作未执行、已执行以及重复补偿等情况。
以上简单介绍了Seata的状态机定义语法及其含义。
3.5.2 表结构
在Seata Saga模式下,会在协同中心的数据库中保存状态机定义以及状态机执行日志,因此,需要在数据库中新增三张表。
第一张表是seata_state_machine_def,用于保存状态机定义,即对应着JSON:
sql
CREATE TABLE IF NOT EXISTS seata_state_machine_def (
id VARCHAR(128) NOT NULL COMMENT '状态机定义 ID,唯一标识一个流程定义版本' PRIMARY KEY,
name VARCHAR(128) NOT NULL COMMENT '状态机名称,对应流程 JSON 的 Name',
tenant_id VARCHAR(32) NOT NULL COMMENT '租户标识,用于隔离流程定义',
app_name VARCHAR(32) COMMENT '所属应用名称',
type VARCHAR(20) COMMENT '状态机定义类型',
comment_ VARCHAR(255) COMMENT '状态机定义的描述信息',
ver VARCHAR(16) NOT NULL COMMENT '状态机定义版本,对应流程 JSON 的 Version',
gmt_create DATETIME(3) NOT NULL COMMENT '定义创建时间,精确到毫秒',
status VARCHAR(2) NOT NULL COMMENT '状态机定义的启用状态',
content LONGTEXT COMMENT '状态机定义 JSON,包含节点、路由和补偿配置',
recover_strategy VARCHAR(16) COMMENT '故障恢复策略:Compensate 补偿,Forward 向前重试',
UNIQUE KEY uk_saga_definition (name, tenant_id, ver)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='Saga 状态机定义:保存流程 JSON 及其版本';第二张表是seata_state_machine_inst,即状态机执行记录,执行一次状态机,会在该表中新增一条记录:
sql
CREATE TABLE IF NOT EXISTS seata_state_machine_inst (
id VARCHAR(128) NOT NULL COMMENT '流程实例 ID;当前接入 Seata Server 时使用全局事务 XID' PRIMARY KEY,
machine_id VARCHAR(128) NOT NULL COMMENT '关联的状态机定义 ID,对应 seata_state_machine_def.id',
tenant_id VARCHAR(32) NOT NULL COMMENT '租户标识,与业务标识共同限定流程实例唯一性',
parent_id VARCHAR(128) COMMENT '父流程实例 ID,用于子状态机,顶层流程为空',
business_key VARCHAR(128) COMMENT '业务标识,当前订单流程使用 order:订单ID',
gmt_started DATETIME(3) NOT NULL COMMENT '流程开始时间,精确到毫秒',
gmt_end DATETIME(3) COMMENT '流程结束时间,未结束时为空',
gmt_updated DATETIME(3) COMMENT '流程更新时间,也用于乐观并发控制',
status VARCHAR(2) COMMENT '正向执行状态:RU 执行中、SU 成功、FA 失败、UN 未知',
compensation_status VARCHAR(2) COMMENT '补偿执行状态:RU 执行中、SU 成功、FA 失败、UN 未知;未触发时为空',
is_running TINYINT COMMENT '流程是否正在执行:1 是,0 否',
start_params LONGTEXT COMMENT 'JSON 格式的流程启动参数',
end_params LONGTEXT COMMENT 'JSON 格式的流程结束参数',
excep LONGBLOB COMMENT 'Java 序列化的流程异常,使用二进制存储',
UNIQUE KEY uk_saga_business (business_key, tenant_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='Saga 状态机执行实例:记录一次业务流程的执行及补偿状态';第三张表是seata_state_inst,记录的是状态机中的状态节点执行结果:
sql
CREATE TABLE IF NOT EXISTS seata_state_inst (
id VARCHAR(128) NOT NULL COMMENT '节点执行实例 ID,与流程实例 ID 组成主键',
machine_inst_id VARCHAR(128) NOT NULL COMMENT '所属流程实例 ID,对应 seata_state_machine_inst.id',
name VARCHAR(128) NOT NULL COMMENT '节点名称,对应流程 JSON 中 States 的键',
type VARCHAR(20) COMMENT '节点类型,例如 ServiceTask、Choice',
service_name VARCHAR(128) COMMENT '调用的服务名称,Spring Bean 调用时为 Bean 名称',
service_method VARCHAR(128) COMMENT '调用的服务方法名称',
service_type VARCHAR(16) COMMENT '服务调用类型,例如 Spring Bean 调用',
business_key VARCHAR(128) COMMENT '节点执行的业务标识',
state_id_compensated_for VARCHAR(128) COMMENT '当前补偿节点所对应的原节点执行实例 ID',
state_id_retried_for VARCHAR(128) COMMENT '当前重试节点所对应的原节点执行实例 ID',
gmt_started DATETIME(3) NOT NULL COMMENT '节点开始时间,精确到毫秒',
gmt_end DATETIME(3) COMMENT '节点结束时间,未结束时为空',
gmt_updated DATETIME(3) COMMENT '节点执行记录的更新时间,精确到毫秒',
is_for_update TINYINT COMMENT '是否为更新型业务节点:1 是,0 否;不表示 SQL 行锁',
input_params LONGTEXT COMMENT 'JSON 格式的节点调用入参',
output_params LONGTEXT COMMENT 'JSON 格式的节点调用返回结果',
status VARCHAR(2) COMMENT '节点执行状态:RU 执行中、SU 成功、FA 失败、UN 未知',
excep LONGBLOB COMMENT 'Java 序列化的节点异常,使用二进制存储',
PRIMARY KEY (id, machine_inst_id),
KEY idx_saga_machine (machine_inst_id, gmt_started)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='Saga 节点执行实例:记录节点调用、执行结果及补偿重试关联';3.5.3 配置Bean
需要向Spring容器中注入两个配置类:DbStateMachineConfig和StateMachineEngine
DbStateMachineConfig:用于配置Seata Saga相关属性配置 作用 setDataSource(dataSource)指定 Saga 状态持久化的数据源 setApplicationId(applicationId)设置向 Seata Server注册事务时使用的应用标识 setTxServiceGroup(txServiceGroup)设置 Seata 事务服务组,用于 TC 路由 setDefaultTenantId("default")设置状态机默认租户标识 setResources(...)指定 StateLang JSON 状态机定义文件 setSagaJsonParser("jackson")选择 Saga 参数 JSON 序列化实现 setEnableAsync(false)禁用状态机的异步执行能力 setTransOperationTimeout(30000)设置事务相关操作的超时参数,单位毫秒 setServiceInvokeTimeout(10000)设置服务调用超时参数,单位毫秒 setSagaBranchRegisterEnable(false)是否启用 Saga 分支向 TC 注册 config.setDefaultTenantId("default")的作用是:给 Seata Saga 状态机设置默认租户 ID,用于区分不同租户下的状态机定义和执行实例。假设系统中有两个 Saga 流程:
- 订单业务:
CreateOrderSaga - 采购业务:
CreatePurchaseSaga
可以按业务域划分租户:
TenantId 状态机名称 用途 orderCreateOrderSaga创建订单 purchaseCreatePurchaseSaga创建采购单 orderCancelOrderSaga取消订单 在 Seata 中,状态机定义的查询可以通过 状态机名称 + TenantId 定位。
假设两个业务域都定义了名为
CreateOrderSaga的状态机,但处理流程不同:TenantId = mall CreateOrderSaga ├── 扣库存 └── 扣余额 TenantId = pharmacy CreateOrderSaga ├── 检查药品资质 ├── 扣库存 └── 扣余额虽然状态机名称一样,但 TenantId 不同,因此可以区分对应的状态机定义。在 Seata 状态机定义表中,也有
tenant_id字段,用于保存这个标识。setSagaBranchRegisterEnable(true)的作用是让 Seata Saga 在执行符合分支注册条件的业务节点(State)时,向 Seata Server(TC)注册一个分支事务,并在节点执行结束后向 TC 报告执行状态。默认不开启。假设订单服务部署了 Saga 状态机引擎:
订单服务(Saga 应用) │ ├── 节点 A:扣减库存 │ ├── 节点 B:扣减余额 │ └── 节点 C:更新订单状态当设置为
true时,执行过程如下:
假设TC 中记录如下(ID 和状态仅作示意):
全局事务 XID = 10001 │ ├── 分支 101:扣减库存 → 成功 ├── 分支 102:扣减余额 → 成功 └── 分支 103:更新订单 → 失败这样,TC 就能够感知已经注册了哪些业务分支,以及收到报告的执行结果。
注意:分支事务并不等于一个数据库连接或一个独立的微服务。它是 Seata 为 Saga 执行步骤创建的事务管理记录。
- 订单业务:
StateMachineEngine:状态机引擎,可以在业务中注入该引擎;
java
@Configuration(proxyBeanMethods=false)
@EnableScheduling
public class SagaConfiguration {
@Bean
// 尽可能让 Spring Boot 已识别的数据库初始化任务先完成,再初始化该 Bean。
// 因为 DbStateMachineConfig 在初始化时需要访问数据库,并构建数据库状态存储组件
@DependsOnDatabaseInitialization
public DbStateMachineConfig sagaStateMachineConfig(DataSource dataSource,
@Value("${spring.application.name}") String applicationId,
@Value("${seata.tx-service-group}") String txServiceGroup) {
var config = new DbStateMachineConfig();
config.setDataSource(dataSource);
config.setApplicationId(applicationId);
config.setTxServiceGroup(txServiceGroup);
config.setDefaultTenantId("default");
config.setResources(new String[]{"classpath*:statelang/*.json"});
config.setSagaJsonParser("jackson");
config.setEnableAsync(false);
config.setTransOperationTimeout(30000);
config.setServiceInvokeTimeout(10000);
config.setSagaBranchRegisterEnable(false);
return config;
}
@Bean
public StateMachineEngine stateMachineEngine(DbStateMachineConfig config) {
var engine = new ProcessCtrlStateMachineEngine();
engine.setStateMachineConfig(config);
StateMachineEngineHolder.setStateMachineEngine(engine);
// Seata 2.5 的兼容 SPI 可能选择 io.seata SagaResourceManager,两个入口共享同一配置和存储。
var compatibleEngine = new io.seata.saga.engine.impl.ProcessCtrlStateMachineEngine();
compatibleEngine.setStateMachineConfig(io.seata.saga.engine.impl.DefaultStateMachineConfig.wrap(config));
io.seata.saga.rm.StateMachineEngineHolder.setStateMachineEngine(compatibleEngine);
return engine;
}
}3.5.4 Saga案例项目
Saga测试案例模拟下单接口,使用Saga模式,即下单流程涉及创建订单->扣减库存->扣减余额,其中扣减库存和扣减余额都通过feign接口调用其他服务(stock-service和account-service)。如果某个步骤操作失败,则通过补偿接口回退。
完整项目参考:https://github.com/Lee-0o0/seata-demo/tree/saga
首先在order-service服务中定义Feign接口:
java
@Component("orderSagaActions")
public class OrderSagaActions {
// feignClient-库存
private final StockClient stock;
// feignClient-账户
private final AccountClient account;
// 订单操作mapper
private final OrderMapper orders;
public OrderSagaActions(StockClient stock, AccountClient account, OrderMapper orders) {
this.stock = stock; this.account = account; this.orders = orders;
}
private org.example.orderservice.entity.PurchaseOrder snapshot(String requestId, Long userId,
Long productId, Integer quantity, String unitPrice, String totalAmount, Boolean simulateFailure) {
var order = new org.example.orderservice.entity.PurchaseOrder();
order.setRequestId(requestId); order.setUserId(userId); order.setProductId(productId);
order.setQuantity(quantity); order.setUnitPrice(new java.math.BigDecimal(unitPrice));
order.setTotalAmount(new java.math.BigDecimal(totalAmount)); order.setSimulateFailure(simulateFailure);
order.setCreatedAt(java.time.LocalDateTime.now().withNano(0));
return order;
}
// 创建订单
public boolean createOrder(String requestId, Long userId, Long productId, Integer quantity,
String unitPrice, String totalAmount, Boolean simulateFailure) {
var order = snapshot(requestId, userId, productId, quantity, unitPrice, totalAmount, simulateFailure);
order.setStatus("PROCESSING");
orders.insert(order);
if ("CLOSED".equals(orders.findByRequestId(requestId).getStatus())) {
throw new IllegalStateException("订单已关闭");
}
return true;
}
// 关闭订单
@org.springframework.transaction.annotation.Transactional
public boolean closeOrder(String requestId, Long userId, Long productId, Integer quantity,
String unitPrice, String totalAmount, Boolean simulateFailure) {
// 空补偿也留下关闭记录;事务及唯一键保证迟到的创建不能重新打开订单。
var order = snapshot(requestId, userId, productId, quantity, unitPrice, totalAmount, simulateFailure);
order.setStatus("CLOSED");
orders.insert(order);
orders.closeOrder(requestId);
return true;
}
// 扣减余额
public boolean deductStock(String requestId) {
var order = orders.findByRequestId(requestId);
stock.deduct("order:" + order.getId() + ":stock", order.getProductId(), order.getQuantity());
return true;
}
// 还回余额
public boolean debitAccount(String requestId) {
var order = orders.findByRequestId(requestId);
account.debit("order:" + order.getId() + ":account", order.getUserId(), order.getTotalAmount());
return true;
}
// 扣减库存
public boolean compensateStock(String requestId) {
stock.compensate("order:" + orders.findByRequestId(requestId).getId() + ":stock");
return true;
}
//还回库存
public boolean compensateAccount(String requestId) {
account.compensate("order:" + orders.findByRequestId(requestId).getId() + ":account");
return true;
}
// 确认订单
public boolean confirmOrder(String requestId) {
if (Boolean.TRUE.equals(orders.findByRequestId(requestId).getSimulateFailure())) {
throw new IllegalStateException("模拟扣减完成后的订单异常");
}
orders.updateStatus(orders.findByRequestId(requestId).getId(), "SUCCESS");
if (!"SUCCESS".equals(orders.findByRequestId(requestId).getStatus())) {
throw new IllegalStateException("已关闭订单不能确认");
}
return true;
}
}定义状态机:
json
{
"Name": "orderSaga",
"Version": "3.0.0",
"StartState": "CreateOrder",
"RecoverStrategy": "Compensate",
"States": {
"CreateOrder": {
"Type": "ServiceTask",
"ServiceName": "orderSagaActions",
"ServiceMethod": "createOrder",
"Input": [
"$.[requestId]",
"$.[userId]",
"$.[productId]",
"$.[quantity]",
"$.[unitPrice]",
"$.[totalAmount]",
"$.[simulateFailure]"
],
"IsForUpdate": true,
"Status": {
"#root == true": "SU",
"$Exception{java.lang.Throwable}": "UN"
},
"Catch": [
{
"Exceptions": [
"java.lang.Throwable"
],
"Next": "CompensationTrigger"
}
],
"Next": "DeductStock",
"CompensateState": "CloseOrder"
},
"DeductStock": {
"Type": "ServiceTask",
"ServiceName": "orderSagaActions",
"ServiceMethod": "deductStock",
"Input": [
"$.[requestId]"
],
"IsForUpdate": true,
"Status": {
"#root == true": "SU",
"$Exception{java.lang.Throwable}": "UN"
},
"Catch": [
{
"Exceptions": [
"java.lang.Throwable"
],
"Next": "CompensationTrigger"
}
],
"Next": "DebitAccount",
"CompensateState": "CompensateStock"
},
"DebitAccount": {
"Type": "ServiceTask",
"ServiceName": "orderSagaActions",
"ServiceMethod": "debitAccount",
"Input": [
"$.[requestId]"
],
"IsForUpdate": true,
"Status": {
"#root == true": "SU",
"$Exception{java.lang.Throwable}": "UN"
},
"Catch": [
{
"Exceptions": [
"java.lang.Throwable"
],
"Next": "CompensationTrigger"
}
],
"Next": "ConfirmOrder",
"CompensateState": "CompensateAccount"
},
"CompensateStock": {
"Type": "ServiceTask",
"ServiceName": "orderSagaActions",
"ServiceMethod": "compensateStock",
"Input": [
"$.[requestId]"
],
"Status": {
"#root == true": "SU",
"$Exception{java.lang.Throwable}": "UN"
}
},
"CompensateAccount": {
"Type": "ServiceTask",
"ServiceName": "orderSagaActions",
"ServiceMethod": "compensateAccount",
"Input": [
"$.[requestId]"
],
"Status": {
"#root == true": "SU",
"$Exception{java.lang.Throwable}": "UN"
}
},
"CompensationTrigger": {
"Type": "CompensationTrigger",
"Next": "Fail"
},
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail",
"ErrorCode": "ORDER_FAILED",
"Message": "订单流程失败"
},
"ConfirmOrder": {
"Type": "ServiceTask",
"ServiceName": "orderSagaActions",
"ServiceMethod": "confirmOrder",
"Input": [
"$.[requestId]"
],
"IsForUpdate": true,
"Status": {
"#root == true": "SU",
"$Exception{java.lang.Throwable}": "UN"
},
"Catch": [
{
"Exceptions": [
"java.lang.Throwable"
],
"Next": "CompensationTrigger"
}
],
"Next": "Succeed",
"CompensateState": "CloseOrder"
},
"CloseOrder": {
"Type": "ServiceTask",
"ServiceName": "orderSagaActions",
"ServiceMethod": "closeOrder",
"Input": [
"$.[requestId]",
"$.[userId]",
"$.[productId]",
"$.[quantity]",
"$.[unitPrice]",
"$.[totalAmount]",
"$.[simulateFailure]"
],
"Status": {
"#root == true": "SU",
"$Exception{java.lang.Throwable}": "UN"
}
}
}
}在服务中,启动状态机:
java
@Service
public class OrderService {
private static final Logger LOG = LoggerFactory.getLogger(OrderService.class);
private final OrderMapper mapper;
private final ProductMapper products;
private final StateMachineEngine engine;
private final DataSource dataSource;
public OrderService(OrderMapper mapper, ProductMapper products, StateMachineEngine engine, DataSource dataSource) {
this.mapper = mapper; this.products = products; this.engine = engine; this.dataSource = dataSource;
}
// 入口只校验、准备状态机参数;订单由 CreateOrder 节点创建。
public PurchaseOrder create(Long userId, Long productId, Integer quantity, Boolean exception, String requestId) {
// 验证请求是否合理
if (userId == null || userId <= 0 || productId == null || productId <= 0 || quantity == null || quantity <= 0) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "用户 ID、商品 ID 和数量必须大于 0");
}
if (requestId == null) { requestId = UUID.randomUUID().toString(); }
if (!requestId.matches("[A-Za-z0-9:_-]{1,128}")) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "请求 ID 格式不合法");
}
String sagaBusinessKey = businessKey(requestId);
// 同一请求串行启动;锁名使用摘要以满足 MySQL 64 字符限制。
String lockName = sagaBusinessKey.substring("order:".length());
try (var connection = dataSource.getConnection()) {
// 从mysql中获取锁
try (var lock = connection.prepareStatement("SELECT GET_LOCK(?, 10)")) {
lock.setString(1, lockName);
try (var result = lock.executeQuery()) {
if (!result.next() || result.getInt(1) != 1) {
throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE, "请求正在处理中,请使用相同请求 ID 重试");
}
}
}
try {
// 获取订单
var order = mapper.findByRequestId(requestId);
if (order != null) {
// 之前已经用相同请求创建了订单,校验参数
validateSameRequest(order, userId, productId, quantity, exception);
return get(order.getId());
}
// 此时没有订单
// 获取状态机实例
var instance = instanceByKey(sagaBusinessKey);
if (instance != null) {
// 状态机实例不为空,说明相同的请求已经启动了状态机
// 但此时还没有订单创建,校验参数后复用已有流程,避免重复启动,恢复由 TC 驱动。
// 已有流程会继续查订单,如果还不存在,不会继续启动状态机,而是由TC恢复
validateSameRequest(instance.getStartParams(), userId, productId, quantity, exception);
} else {
// 订单不存在,状态机不存在,启动正常流程
// 校验
BigDecimal price = products.price(productId);
if (price == null) { throw new ResponseStatusException(HttpStatus.NOT_FOUND, "商品不存在"); }
BigDecimal total = price.multiply(BigDecimal.valueOf(quantity));
if (total.precision() > 19) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "订单金额超出范围");
}
// 金额使用十进制字符串,避免恢复反序列化时的浮点误差。
var params = new HashMap<String, Object>();
params.put("requestId", requestId); params.put("userId", userId);
params.put("productId", productId); params.put("quantity", quantity);
params.put("unitPrice", price.toPlainString()); params.put("totalAmount", total.toPlainString());
params.put("simulateFailure", Boolean.TRUE.equals(exception));
try {
// 启动状态机
// stateMachineName : 状态机名称,与json配置文件中的名称一致
// tenantId : 租户名称,自定义
// businessKey : 业务标识,用于关联业务数据与状态机执行实例
// startParams :启动参数,传递给状态机中的各个节点使用
engine.startWithBusinessKey("orderSaga", "order", sagaBusinessKey, params);
} catch (RuntimeException failure) {
LOG.warn("请求 {} Saga 执行未完成,已持久化实例由 TC 恢复", requestId, failure);
}
}
// 创建之后查询,返回结果
order = mapper.findByRequestId(requestId);
if (order == null) {
throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE, "订单尚未创建,请使用相同请求 ID 重试");
}
return get(order.getId());
} finally {
// 释放锁
try (var release = connection.prepareStatement("SELECT RELEASE_LOCK(?)")) {
release.setString(1, lockName); release.execute();
}
}
} catch (java.sql.SQLException failure) {
throw new IllegalStateException("订单 Saga 执行锁失败", failure);
}
}
private void validateSameRequest(PurchaseOrder order, Long userId, Long productId, Integer quantity, Boolean exception) {
if (!userId.equals(order.getUserId()) || !productId.equals(order.getProductId())
|| !quantity.equals(order.getQuantity()) || Boolean.TRUE.equals(exception) != Boolean.TRUE.equals(order.getSimulateFailure())) {
throw new ResponseStatusException(HttpStatus.CONFLICT, "请求 ID 已用于不同的订单参数");
}
}
private void validateSameRequest(Map<String, Object> params, Long userId, Long productId,
Integer quantity, Boolean exception) {
if (params == null) {
throw new IllegalStateException("Saga 实例缺少下单启动参数");
}
if (!sameNumber(params.get("userId"), userId) || !sameNumber(params.get("productId"), productId)
|| !sameNumber(params.get("quantity"), quantity)
|| Boolean.TRUE.equals(params.get("simulateFailure")) != Boolean.TRUE.equals(exception)) {
throw new ResponseStatusException(HttpStatus.CONFLICT, "请求 ID 已用于不同的订单参数");
}
}
private boolean sameNumber(Object stored, Number requested) {
// 持久化 JSON 反序列化可能将 Long 变为 Integer,按数值比较。
return stored instanceof Number && new BigDecimal(stored.toString())
.compareTo(new BigDecimal(requested.toString())) == 0;
}
private String businessKey(String requestId) {
try {
return "order:" + HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256")
.digest(requestId.getBytes(StandardCharsets.US_ASCII)));
} catch (NoSuchAlgorithmException impossible) {
throw new IllegalStateException(impossible);
}
}
private StateMachineInstance instanceByKey(String sagaBusinessKey) {
return engine.getStateMachineConfig().getStateLogRepository().getStateMachineInstanceByBusinessKey(sagaBusinessKey, "order");
}
private StateMachineInstance synchronizeStatus(PurchaseOrder order) {
var instance = instanceByKey(businessKey(order.getRequestId()));
if (instance == null) { return null; }
if (ExecutionStatus.SU == instance.getCompensationStatus()) {
// 状态机补偿状态已完成,关闭订单
mapper.closeOrder(order.getRequestId());
} else if (!instance.isRunning() && ExecutionStatus.SU == instance.getStatus()
&& instance.getCompensationStatus() == null) {
// 状态机结束运行,并且补偿状态为空,表示成功
mapper.updateStatus(order.getId(), "SUCCESS");
} else if (instance.getCompensationStatus() != null || ExecutionStatus.UN == instance.getStatus()
|| ExecutionStatus.FA == instance.getStatus()) {
// 状态机正在补偿
mapper.updateStatus(order.getId(), "COMPENSATING");
}
return instance;
}
@Scheduled(fixedDelayString="${saga.recovery-delay-ms:5000}")
public void recover() {
// 已启动流程由 TC 恢复;这里只同步订单状态,不从订单表补启动流程。
for (long id : mapper.pending()) {
try { synchronizeStatus(mapper.findById(id)); }
catch (RuntimeException failure) { LOG.error("订单 {} Saga 状态同步失败", id, failure); }
}
}
public PurchaseOrder get(long id) {
if (id <= 0) { throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "订单 ID 必须大于 0"); }
PurchaseOrder order = mapper.findById(id);
if (order == null) { throw new ResponseStatusException(HttpStatus.NOT_FOUND, "订单不存在"); }
var instance = synchronizeStatus(order);
order = mapper.findById(id);
// 订单关闭节点可能先于其他补偿完成;响应仍应展示整个流程的状态。
if (instance != null && ExecutionStatus.SU != instance.getCompensationStatus()
&& (instance.getCompensationStatus() != null || ExecutionStatus.UN == instance.getStatus()
|| ExecutionStatus.FA == instance.getStatus())) {
order.setStatus("COMPENSATING");
} else if (instance != null && instance.isRunning() && "SUCCESS".equals(order.getStatus())) {
order.setStatus("PROCESSING");
}
return order;
}
}参考资料
[1] Seata官方文档:https://seata.apache.org/docs/overview/what-is-seata
[3] 在IDEA中执行HTTP请求:https://www.jetbrains.com/help/idea/http-client-in-product-code-editor.html