基于业务层两阶段提交的 TCC 分布式事务原理与防坑实践

CREATE TABLE account (
    user_id           BIGINT PRIMARY KEY,
    available_balance DECIMAL(12, 2) NOT NULL DEFAULT 0.00, -- 可用余额
    frozen_balance    DECIMAL(12, 2) NOT NULL DEFAULT 0.00  -- 冻结余额
);

@LocalTCC
public interface AccountTccService {
 
    /**
     * 第一阶段：Try 方法
     * 定义两阶段动作名称，并指定 Confirm 和 Cancel 方法名
     */
    @TwoPhaseBusinessAction(
        name = "prepareDeductAccount", 
        commitMethod = "confirmDeduct", 
        rollbackMethod = "cancelDeduct"
    )
    boolean prepareDeduct(
        BusinessActionContext context,
        @BusinessActionContextParameter(paramName = "userId") Long userId,
        @BusinessActionContextParameter(paramName = "amount") BigDecimal amount
    );
 
    /**
     * 第二阶段：Confirm 确认方法
     */
    boolean confirmDeduct(BusinessActionContext context);
 
    /**
     * 第二阶段：Cancel 取消方法
     */
    boolean cancelDeduct(BusinessActionContext context);
}

CREATE TABLE tcc_transaction_record (
    xid           VARCHAR(128) NOT NULL, -- 全局事务 ID
    branch_id     BIGINT NOT NULL,       -- 分支事务 ID
    status        TINYINT NOT NULL,      -- 状态: 1-TRIED, 2-CONFIRMED, 3-CANCELLED
    gmt_create    DATETIME NOT NULL,
    PRIMARY KEY (xid, branch_id)
);

@Transactional(rollbackFor = Exception.class)
public boolean prepareDeduct(BusinessActionContext context, Long userId, BigDecimal amount) {
    String xid = context.getXid();
    long branchId = context.getBranchId();
 
    // 1. 检查控制表记录
    TccRecord record = tccRecordMapper.select(xid, branchId);
    
    // 防悬挂判定：若记录已存在且为 CANCELLED，说明 Cancel 先到了，绝不能再执行 Try
    if (record != null && record.getStatus() == Status.CANCELLED) {
        log.warn("检测到业务悬挂请求，xid: {}, branchId: {}，拒绝执行", xid, branchId);
        return false;
    }
 
    // 2. 执行业务层资金冻结
    int updated = accountMapper.freezeBalance(userId, amount);
    if (updated == 0) {
        throw new BusinessException("可用余额不足，冻结失败");
    }
 
    // 3. 插入控制记录，状态标记为 TRIED
    tccRecordMapper.insert(new TccRecord(xid, branchId, Status.TRIED));
    return true;
}

@Transactional(rollbackFor = Exception.class)
public boolean confirmDeduct(BusinessActionContext context) {
    String xid = context.getXid();
    long branchId = context.getBranchId();
 
    TccRecord record = tccRecordMapper.select(xid, branchId);
    if (record == null) {
        log.error("未找到对应 Try 记录，数据异常，xid: {}", xid);
        return false;
    }
 
    // 幂等处理：若已被 Confirm 过，直接返回成功
    if (record.getStatus() == Status.CONFIRMED) {
        return true;
    }
 
    // 1. 正式扣除冻结余额
    Long userId = (Long) context.getActionContext("userId");
    BigDecimal amount = (BigDecimal) context.getActionContext("amount");
    accountMapper.deductFrozenBalance(userId, amount);
 
    // 2. 更新控制表状态为 CONFIRMED
    tccRecordMapper.updateStatus(xid, branchId, Status.CONFIRMED);
    return true;
}

@Transactional(rollbackFor = Exception.class)
public boolean cancelDeduct(BusinessActionContext context) {
    String xid = context.getXid();
    long branchId = context.getBranchId();
 
    TccRecord record = tccRecordMapper.select(xid, branchId);
 
    // 防空回滚与防悬挂核心逻辑：
    if (record == null) {
        // Try 未执行过，发生空回滚。插入 CANCELLED 记录防悬挂，但不执行解冻业务
        log.info("触发空回滚，防悬挂标记落库，xid: {}", xid);
        tccRecordMapper.insert(new TccRecord(xid, branchId, Status.CANCELLED));
        return true;
    }
 
    // 幂等处理：若已被 Cancel 过，直接返回成功
    if (record.getStatus() == Status.CANCELLED) {
        return true;
    }
 
    // 1. 正常回滚：退还冻结金额至可用余额
    Long userId = (Long) context.getActionContext("userId");
    BigDecimal amount = (BigDecimal) context.getActionContext("amount");
    accountMapper.unfreezeBalance(userId, amount);
 
    // 2. 更新控制表状态为 CANCELLED
    tccRecordMapper.updateStatus(xid, branchId, Status.CANCELLED);
    return true;
}