tcc-transaction 分布式事务框架实战:TCC 模型原理、两阶段调用与自动恢复机制深度解析

原创2026-10-14 22:03:251,996 阅读
文章标签:后端微服务

tcc-transaction 分布式事务框架实战:TCC 模型原理、两阶段调用与自动恢复机制深度解析

tcc-transaction 是一款开源的微服务架构下的 TCC 型(Try-Confirm-Cancel)分布式事务 Java 实现,致力于提供高性能、简单易用的分布式事务服务。本文以 README.md 为主线,结合仓库源码与 http 示例工程,系统讲解 TCC 的 Try/Confirm/Cancel 语义、支付退款类场景的落地流程、两阶段活动管理器的工作机制,以及框架的参与方登记、状态机、幂等与自动恢复等底层实现。读完本文,你将能够理解 tcc-transaction 的核心设计,并参照示例在自己的微服务中编写 @Compensable 业务方法。

一、TCC-TRANSACTION 是什么

TCC 是一种补偿型事务模型,将一笔跨服务业务拆分为三个可独立执行的阶段,三个阶段的语义在 tcc-transaction 中定义得非常明确:

  • Try:尝试执行业务,完成所有业务检查(一致性),预留必须的业务资源(准隔离性)。
  • Confirm:确认执行业务,不做任何业务检查,只使用 Try 阶段预留的业务资源,满足幂等性。
  • Cancel:取消执行业务,释放 Try 阶段预留的业务资源,满足幂等性。

简单来说:Try 阶段"先记账不动账",把需要扣减的资源冻结起来;全部 Try 成功后再由 Confirm 真正落账;任一步骤失败则由 Cancel 把冻结的资源释放回去。这一模型不依赖数据库本地事务,天然适合跨服务、跨数据库的分布式调用场景。

在仓库中,TCC 三阶段的语义通过 @Compensable 注解直接映射到业务方法上,见 Compensable.java:

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
public @interface Compensable {
    Propagation propagation() default Propagation.REQUIRED;
    String confirmMethod() default "";
    String cancelMethod() default "";
    boolean asyncConfirm() default false;
    boolean asyncCancel() default false;
    Class<? extends Exception>[] delayCancelExceptions() default {};
}

其中 confirmMethod 与 cancelMethod 分别指定 Confirm、Cancel 阶段要回调的方法名,asyncConfirm / asyncCancel 决定确认与取消是否异步执行,delayCancelExceptions 用于声明"遇到此类异常时延迟取消"的特例。

二、微服务架构中的分布式事务问题

随着传统单体架构微服务化,原本单体架构中不同模块被拆分为若干个功能简单、松耦合的服务。系统微服务化后,一个业务操作内部可能需要调用多个服务并操作多个数据库,服务调用间的分布式事务问题因此变得非常突出。

README 中给出的典型场景是支付退款:

支付退款场景需要从各分账方退回平台收益户(退分账),再退还给付款方。

其中"退分账"阶段涉及从多个分账方账户扣款,包括商家 1 收益户、商家 2 收益户、商家 3 收益户以及平台手续费账户。这些账户分布在不同数据库,如果商家 3 收益户扣款失败,其他已经成功的扣款必须回滚,这时就需要分布式事务来保证一致性。

支付退款流程

该场景的业务特征在于:一次操作横跨多个独立数据库,任何一个参与方的失败都必须触发全局回滚,而各数据库之间无法借助单一的本地事务完成原子提交。

三、如何解决:tcc-transaction 在退款场景的执行流程

针对上述"退分账"问题,tcc-transaction 的处理方式是把扣款拆成"冻结"与"扣除/解冻"两步,分阶段推进:

  • Try 阶段:各账户分别执行冻结操作
    • 商家 1 收益户 -> 冻结分账金额
    • 商家 2 收益户 -> 冻结分账金额
    • 商家 3 收益户 -> 冻结分账金额
    • 平台手续费 -> 冻结手续费
  • Try 成功 => Confirm 阶段:真正完成资金转移
    • 商家 1 收益户 -> 扣除分账金额
    • 商家 2 收益户 -> 扣除分账金额
    • 商家 3 收益户 -> 扣除分账金额
    • 平台手续费 -> 扣除手续费
    • 平台收益户 -> 增加金额(总分账金额 + 手续费)
  • Try 失败 => Cancel 阶段:释放冻结资源
    • 商家 1 收益户 -> 解冻分账金额
    • 商家 2 收益户 -> 解冻分账金额
    • 商家 3 收益户 -> 解冻分账金额
    • 平台手续费 -> 解冻手续费

可以看到,TCC 把"扣款"这一风险操作延迟到 Confirm 阶段,而 Try 阶段只是做资源预占(准隔离性),从而把跨库事务的失败窗口压缩到可重试、可补偿的范围内。

仓库中的 http 示例工程 正是这一思路的落地:主业务 makePayment 方法上加 @Compensable,Try 阶段通过 Feign 客户端调用资金(capital)与红包(redpacket)两个从业务服务完成资源预占:

@Compensable(confirmMethod = "confirmMakePayment", cancelMethod = "cancelMakePayment",
        asyncConfirm = true, delayCancelExceptions = {SocketTimeoutException.class})
@Transactional
public void makePayment(String orderNo) {
    Order order = orderRepository.findByMerchantOrderNo(orderNo);
    String result = tradeOrderServiceProxy.record(buildCapitalTradeOrderDto(order));
    String result2 = tradeOrderServiceProxy.record(buildRedPacketTradeOrderDto(order));
    // 模拟 Try 阶段业务失败,触发 Cancel
    if (order.getRedPacketPayAmount().intValue() % 10 == 0) {
        throw new RuntimeException();
    }
}

对应的 Confirm 与 Cancel 方法为 confirmMakePayment、cancelMakePayment,它们与 Try 方法共享同一份入参(如 orderNo),框架在第二阶段通过反射按方法名回调。示例源码位于 tcc-transaction-http-order。

四、工作原理:两阶段活动管理器

tcc-transaction 的整体执行遵循经典的两阶段模型,README 中给出的原理流程如下:

TCC原理

  • 第一阶段:主业务服务分别调用所有从业务的 Try 操作,并在活动管理器中登记所有从业务服务。当所有从业务服务的 Try 操作都调用成功,或者某个从业务服务的 Try 操作失败时,进入第二阶段。
  • 第二阶段:活动管理器根据第一阶段的执行结果执行 Confirm 或 Cancel 操作。
    • 如果第一阶段所有 Try 操作都成功,则活动管理器调用所有从业务服务的 Confirm 操作;
    • 否则调用所有从业务服务的 Cancel 操作。

需要注意的是,第二阶段的 Confirm 或 Cancel 操作本身也是满足最终一致性的过程:在调用 Confirm 或 Cancel 时也可能因为网络等原因导致调用失败,所以活动管理器必须支持重试能力,同时这也就要求 Confirm 和 Cancel 操作具有幂等性。

从源码实现看,"活动管理器"即 TransactionManager.java。它在 begin 时创建根事务(TransactionType.ROOT),Try 阶段通过 enlistParticipant 把每个被调用的从业务登记为参与者并持久化;Try 全部成功后调用 commit(将事务状态置为 CONFIRMING 后执行 Confirm),Try 失败则调用 rollback(将状态置为 CANCELLING 后执行 Cancel):

public void commit(boolean asyncCommit) {
    final Transaction transaction = getCurrentTransaction();
    transaction.setStatus(TransactionStatus.CONFIRMING);
    transactionRepository.update(transaction);
    if (asyncCommit) {
        // 异步提交:交给 asyncTerminatorExecutorService 线程池执行
        asyncTerminatorExecutorService.submit(() -> commitTransaction(transaction));
    } else {
        commitTransaction(transaction);
    }
}

private void commitTransaction(Transaction transaction) {
    try {
        transaction.commit();                    // 依次调用所有参与者的 confirm 方法
        transactionRepository.delete(transaction);
    } catch (Throwable commitException) {
        transactionRepository.update(transaction);
        logger.warn("compensable transaction confirm failed, recovery job will try to confirm later.", commitException);
        throw new ConfirmingException(commitException);
    }
}

commit / rollback 失败后,事务并不会被丢弃,而是保留在事务仓库中,等待**恢复任务(recovery job)**后续重试——这正是"最终一致性"的落点。

五、源码级实现剖析

5.1 事务与参与方的状态机

tcc-transaction 用两个核心枚举管理状态流转,分别位于 TransactionStatus.java 与 ParticipantStatus.java:

  • 事务状态 TransactionStatus:TRYING(1)、CONFIRMING(2)、CANCELLING(3)、TRY_SUCCESS(11)、TRY_FAILED(12)。从源码看,TRYING 表示第一阶段执行中,TRY_SUCCESS / TRY_FAILED 表示分支事务 Try 的结果,CONFIRMING / CANCELLING 表示已进入第二阶段的确认或取消流程。
  • 事务类型 TransactionType(见 TransactionType.java):ROOT(1) 根事务、BRANCH(2) 分支事务。主业务发起的是根事务,跨服务传递时对端创建的是分支事务。

参与者的状态则记录在 Participant.java 中:默认 TRYING,Try 成功置为 TRY_SUCCESS,Try 失败置为 TRY_FAILED;Confirm 执行完毕后置为 CONFIRM_SUCCESS,Cancel 执行完毕后置为 CANCEL_SUCCESS。这些状态正是幂等重试的判断依据。

5.2 事务上下文与传播行为

跨服务传递的关键载体是 TransactionContext.java,它携带 xid(分支事务标识)、rootXid(根事务标识)、rootDomain(根域)以及当前状态 status 与参与方状态 participantStatus。当主业务调用从业务时,框架通过 TransactionContextEditor 将上下文注入到 RPC 参数中(HTTP/Dubbo/gRPC 各有对应实现,如 tcc-transaction-http、tcc-transaction-dubbo、tcc-transaction-grpc 模块)。

传播行为由 Propagation.java 定义,取值与 Spring 事务传播语义一致:

取值 语义
REQUIRED 默认值,当前存在事务则加入,否则新建
SUPPORTS 当前存在事务则加入,否则以非事务方式执行
MANDATORY 当前必须存在事务,否则抛异常
REQUIRES_NEW 总是新建独立事务

5.3 参与者角色判定与两阶段回调

拦截器 CompensableTransactionInterceptor.java 会根据当前线程是否存在活动事务、方法上是否有 @Compensable 注解、以及是否携带 TransactionContext,判定方法扮演的角色并走不同分支:

  • ROOT 角色:方法带 @Compensable、当前无活动事务且无事务上下文。此时调用 transactionManager.begin(...) 开启根事务,执行 Try 主体逻辑;成功后 commit(asyncConfirm),失败则 rollback(asyncCancel, ...) 并向上抛出异常。整体用 finally 中的 cleanAfterCompletion 清理线程局部事务栈。
  • PROVIDER 角色:方法带 @Compensable、当前无活动事务但携带事务上下文(即作为被调用的从业务)。拦截器根据上下文中携带的 status 分支处理:
    • TRYING:新建分支事务并执行业务方法,成功后把状态改为 TRY_SUCCESS,失败改为 TRY_FAILED;
    • CONFIRMING:找到分支事务并执行 commit;若事务已不存在则忽略(说明已被确认过,天然幂等);
    • CANCELLING:在分支事务状态为 TRY_SUCCESS / TRY_FAILED / CANCELLING 等可回滚状态时执行 rollback,事务不存在则忽略。

从业务侧 Try 期间的参与方登记由 ResourceCoordinatorInterceptor.java 完成:它在每次跨服务调用前构造 Participant,保存目标类、confirm/cancel 方法名、参数类型与实参(InvocationContext),并通过 transactionManager.enlistParticipant(participant) 登记到当前事务中。

第二阶段真正执行 Confirm / Cancel 回调的是 Terminator.java:它通过反射找到目标类上的 confirm/cancel 方法,注入 TransactionContext 后调用,并在调用结束后清理上下文:

public static Object invoke(TransactionContext transactionContext, Invocation invocation,
                            Class<? extends TransactionContextEditor> transactionContextEditorClass) {
    if (StringUtils.isNotEmpty(invocation.getMethodName())) {
        Object target = FactoryBuilder.factoryOf(invocation.getTargetClass()).getInstance();
        Method method = target.getClass().getMethod(invocation.getMethodName(), invocation.getParameterTypes());
        FactoryBuilder.factoryOf(transactionContextEditorClass).getInstance()
                .set(transactionContext, target, method, invocation.getArgs());
        try {
            return method.invoke(target, invocation.getArgs());
        } finally {
            FactoryBuilder.factoryOf(transactionContextEditorClass).getInstance()
                    .clear(transactionContext, target, method, invocation.getArgs());
        }
    }
    return null;
}

5.4 幂等性如何落地

因为 Confirm / Cancel 可能因网络超时等原因被反复调用,所以框架要求这两个方法必须幂等。从示例 CapitalController.java 可以看到标准的幂等写法:每个阶段先查询单据状态,只有处于 DRAFT(未处理)时才继续处理,处理完立即更新状态:

@Compensable(confirmMethod = "confirmRecord", cancelMethod = "cancelRecord")
@Transactional
public String record(@RequestBody CapitalTradeOrderDto tradeOrderDto) { /* Try:插入 TradeOrder,账户冻结/转出 */ }

@Transactional
public void confirmRecord(CapitalTradeOrderDto tradeOrderDto) {
    TradeOrder tradeOrder = tradeOrderRepository.findByMerchantOrderNo(tradeOrderDto.getMerchantOrderNo());
    // 只有 DRAFT 状态才确认,保证幂等
    if (null != tradeOrder && "DRAFT".equals(tradeOrder.getStatus())) {
        tradeOrder.confirm();
        tradeOrderRepository.update(tradeOrder);
        CapitalAccount transferToAccount = capitalAccountRepository.findByUserId(tradeOrderDto.getOppositeUserId());
        transferToAccount.transferTo(tradeOrderDto.getAmount());
        capitalAccountRepository.save(transferToAccount);
    }
}

同时,框架层面通过 ParticipantStatus 状态位(CONFIRM_SUCCESS / CANCEL_SUCCESS)保证同一参与者的 Confirm / Cancel 只执行一次——见 Transaction.java 的 commit() / rollback() 实现,二者都会跳过已成功的参与者。

5.5 事务存储与自动恢复

框架把"未完成的事务"持久化到事务仓库,作为最终一致性与恢复重试的基础。事务仓库由 TransactionStorage 接口(TransactionStorage.java)定义,提供 create / update / delete / findByXid / markDeleted / restore 等操作;具体实现由 StorageType.java 枚举选定,包括:

  • MEMORY:内存存储(仅测试/演示)
  • JDBC:关系数据库存储,建表脚本见 db.sql
  • REDIS / REDIS_CLUSTER / SHARD_REDIS:Redis 及集群、分片存储
  • ROCKSDB:本地 KV 存储
  • REMOTING:通过 TCC Server 远程存储(对应 tcc-transaction-server 模块)
  • CUSTOMIZED:自定义扩展

以 JDBC 为例,数据库需要两张核心表(见 db.sql):TCC_TRANSACTION 保存事务记录(含 XID、ROOT_XID、DOMAIN、STATUS、RETRIED_COUNT、CONTENT、VERSION、IS_DELETE 等字段,XID 上有唯一索引),TCC_DOMAIN 保存业务域配置(如 MAX_RETRY_COUNT、ALERT_TYPE、DING_ROBOT_URL 等)。连接池参数可通过 JdbcStoreProperties.java 调整,其默认值为 driverClass=com.mysql.jdbc.Driver、jdbcUrl=jdbc:mysql://127.0.0.1:3306/TCC、maxPoolSize=50 等;Redis 相关默认值见 RedisStoreProperties.java。

自动恢复由基于 Quartz 的调度器实现。核心组件包括:

  • RecoveryScheduler.java:为每个业务域注册一个定时任务,按 cronExpression 周期触发,并把事务信息放入 JobDataMap;
  • QuartzRecoveryTask.java:任务执行时取出域名,调用 getTransactionStoreRecovery().startRecover(domain) 扫描未完成事务并驱动 Confirm / Cancel 重试。

恢复相关参数集中定义在 RecoveryProperties.java,主要默认值如下:

配置项 默认值 含义
maxRetryCount 30 单个事务最大重试次数
recoverDuration 30 调度启动延迟(秒)
cronExpression 0/30 * * * * ? 恢复任务执行周期(每 30 秒一次)
fetchPageSize 200 每次扫描的分页大小
concurrentRecoveryThreadCount CPU 核数 × 2 并发恢复线程数
isRecoveryEnabled true 是否启用恢复(客户端)
maxTimeTreatTryingAsFailed 0 Try 阶段最长容忍时间(秒),小于 1 时不允许将 Try 视为失败
quartzClustered false 是否启用 Quartz 集群模式(多实例部署时开启)

从 RecoveryScheduler.java 的实现看,开启 quartzClustered 后框架会自动配置 JobStoreTX 与 JDBC 数据源(默认库 TCC_SERVER),以保证多节点只调度一次恢复任务。这就是 README 中所说的"活动管理器支持重试能力"在代码层面的完整落点。

六、快速开始:参照示例写第一个 TCC 事务

README 中给出了快速开始入口,指向官方快速开始文档与最新可用版本 2.x 说明。结合本仓库,推荐按以下路径上手:

  1. 阅读示例工程:仓库内的 tcc-transaction-tutorial-sample 提供了完整的可运行示例,按 RPC 风格分为 http(Feign + Spring MVC)、dubbo、grpc、multiple-tier(多层级)四套,并配套建库脚本(见 tcc-transaction-tutorial-sample/src/dbscripts)。
  2. 初始化数据库:根据所选存储类型执行 db.sql(JDBC 存储)或 db_init.sql(TCC Server 远程存储)。
  3. 编写主业务:在发起方方法上添加 @Compensable(confirmMethod = "xxx", cancelMethod = "yyy"),实现对应的 Confirm、Cancel 方法,并保证二者幂等;参考 PaymentServiceImpl.java。
  4. 编写从业务:在被调用方同样标注 @Compensable,在 Try 阶段完成资源预占、Confirm 阶段真正落账、Cancel 阶段释放资源,参考 CapitalController.java。
  5. 按需调整恢复参数:修改 RecoveryProperties.java 对应的配置,控制重试次数、调度周期与并发度。

仓库还提供了配套的可视化运维能力:核心模块的 Dashboard 服务与前端管理界面源码分别位于 tcc-transaction-dashboard 与 tcc-transaction-admin-web,其使用说明见 doc/tcc-transaction-dashboard.md。

七、总结

tcc-transaction 用一套清晰的两阶段模型解决了微服务化后的分布式事务难题:Try 阶段完成一致性检查与资源预留,Confirm / Cancel 阶段由活动管理器统一驱动,并借助事务仓库、Quartz 定时恢复与幂等设计把最终一致性落到了工程实处。其核心价值在于不强依赖单一数据库事务,而是把"跨库一致性"转化为"可记录、可重试、可补偿"的调用流程——这正是支付退款、分账、资金转移等强一致场景所需要的。

登录后查看全文
tcc-transaction