1. 概述

Seata API 分为两大类:High-Level API 和 Low-Level API :

  • High-Level API :用于事务边界定义、控制及事务状态查询。
  • Low-Level API :用于控制事务上下文的传播。

2. High-Level API

2.1 GlobalTransaction

全局事务:包括开启事务、提交、回滚、获取当前状态等方法。

  1. public interface GlobalTransaction {
  2. /**
  3. * 开启一个全局事务(使用默认的事务名和超时时间)
  4. */
  5. void begin() throws TransactionException;
  6. /**
  7. * 开启一个全局事务,并指定超时时间(使用默认的事务名)
  8. */
  9. void begin(int timeout) throws TransactionException;
  10. /**
  11. * 开启一个全局事务,并指定事务名和超时时间
  12. */
  13. void begin(int timeout, String name) throws TransactionException;
  14. /**
  15. * 全局提交
  16. */
  17. void commit() throws TransactionException;
  18. /**
  19. * 全局回滚
  20. */
  21. void rollback() throws TransactionException;
  22. /**
  23. * 获取事务的当前状态
  24. */
  25. GlobalStatus getStatus() throws TransactionException;
  26. /**
  27. * 获取事务的 XID
  28. */
  29. String getXid();
  30. }

2.2 GlobalTransactionContext

GlobalTransaction 实例的获取需要通过 GlobalTransactionContext:

  1. /**
  2. * 获取当前的全局事务实例,如果没有则创建一个新的实例。
  3. */
  4. public static GlobalTransaction getCurrentOrCreate() {
  5. GlobalTransaction tx = getCurrent();
  6. if (tx == null) {
  7. return createNew();
  8. }
  9. return tx;
  10. }
  11. /**
  12. * 重新载入给定 XID 的全局事务实例,这个实例不允许执行开启事务的操作。
  13. * 这个 API 通常用于失败的事务的后续集中处理。
  14. * 比如:全局提交超时,后续集中处理通过重新载入该实例,通过实例方法获取事务当前状态,并根据状态判断是否需要重试全局提交操作。
  15. */
  16. public static GlobalTransaction reload(String xid) throws TransactionException {
  17. GlobalTransaction tx = new DefaultGlobalTransaction(xid, GlobalStatus.UnKnown, GlobalTransactionRole.Launcher) {
  18. @Override
  19. public void begin(int timeout, String name) throws TransactionException {
  20. throw new IllegalStateException("Never BEGIN on a RELOADED GlobalTransaction. ");
  21. }
  22. };
  23. return tx;
  24. }

2.3 TransactionalTemplate

事务化模板:通过上述 GlobalTransaction 和 GlobalTransactionContext API 把一个业务服务的调用包装成带有分布式事务支持的服务。

  1. public class TransactionalTemplate {
  2. public Object execute(TransactionalExecutor business) throws TransactionalExecutor.ExecutionException {
  3. // 1. 获取当前全局事务实例或创建新的实例
  4. GlobalTransaction tx = GlobalTransactionContext.getCurrentOrCreate();
  5. // 2. 开启全局事务
  6. try {
  7. tx.begin(business.timeout(), business.name());
  8. } catch (TransactionException txe) {
  9. // 2.1 开启失败
  10. throw new TransactionalExecutor.ExecutionException(tx, txe,
  11. TransactionalExecutor.Code.BeginFailure);
  12. }
  13. Object rs = null;
  14. try {
  15. // 3. 调用业务服务
  16. rs = business.execute();
  17. } catch (Throwable ex) {
  18. // 业务调用本身的异常
  19. try {
  20. // 全局回滚
  21. tx.rollback();
  22. // 3.1 全局回滚成功:抛出原始业务异常
  23. throw new TransactionalExecutor.ExecutionException(tx, TransactionalExecutor.Code.RollbackDone, ex);
  24. } catch (TransactionException txe) {
  25. // 3.2 全局回滚失败:
  26. throw new TransactionalExecutor.ExecutionException(tx, txe,
  27. TransactionalExecutor.Code.RollbackFailure, ex);
  28. }
  29. }
  30. // 4. 全局提交
  31. try {
  32. tx.commit();
  33. } catch (TransactionException txe) {
  34. // 4.1 全局提交失败:
  35. throw new TransactionalExecutor.ExecutionException(tx, txe,
  36. TransactionalExecutor.Code.CommitFailure);
  37. }
  38. return rs;
  39. }
  40. }

模板方法执行的异常:ExecutionException

  1. class ExecutionException extends Exception {
  2. // 发生异常的事务实例
  3. private GlobalTransaction transaction;
  4. // 异常编码:
  5. // BeginFailure(开启事务失败)
  6. // CommitFailure(全局提交失败)
  7. // RollbackFailure(全局回滚失败)
  8. // RollbackDone(全局回滚成功)
  9. private Code code;
  10. // 触发回滚的业务原始异常
  11. private Throwable originalException;

外层调用逻辑 try-catch 这个异常,根据异常编码进行处理:

  • BeginFailure (开启事务失败):getCause() 得到开启事务失败的框架异常,getOriginalException() 为空。
  • CommitFailure (全局提交失败):getCause() 得到全局提交失败的框架异常,getOriginalException() 为空。
  • RollbackFailure (全局回滚失败):getCause() 得到全局回滚失败的框架异常,getOriginalException() 业务应用的原始异常。
  • RollbackDone (全局回滚成功):getCause() 为空,getOriginalException() 业务应用的原始异常。

3. Low-Level API

3.1 RootContext

事务的根上下文:负责在应用的运行时,维护 XID 。

  1. /**
  2. * 得到当前应用运行时的全局事务 XID
  3. */
  4. public static String getXID() {
  5. return CONTEXT_HOLDER.get(KEY_XID);
  6. }
  7. /**
  8. * 将全局事务 XID 绑定到当前应用的运行时中
  9. */
  10. public static void bind(String xid) {
  11. if (LOGGER.isDebugEnabled()) {
  12. LOGGER.debug("bind " + xid);
  13. }
  14. CONTEXT_HOLDER.put(KEY_XID, xid);
  15. }
  16. /**
  17. * 将全局事务 XID 从当前应用的运行时中解除绑定,同时将 XID 返回
  18. */
  19. public static String unbind() {
  20. String xid = CONTEXT_HOLDER.remove(KEY_XID);
  21. if (LOGGER.isDebugEnabled()) {
  22. LOGGER.debug("unbind " + xid);
  23. }
  24. return xid;
  25. }
  26. /**
  27. * 判断当前应用的运行时是否处于全局事务的上下文中
  28. */
  29. public static boolean inGlobalTransaction() {
  30. return CONTEXT_HOLDER.get(KEY_XID) != null;
  31. }

High-Level API 的实现都是基于 RootContext 中维护的 XID 来做的。

应用的当前运行的操作是否在一个全局事务的上下文中,就是看 RootContext 中是否有 XID。

RootContext 的默认实现是基于 ThreadLocal 的,即 XID 保存在当前线程上下文中。

Low-Level API 的两个典型的应用场景:

1. 远程调用事务上下文的传播

远程调用前获取当前 XID:

  1. String xid = RootContext.getXID();

远程调用过程把 XID 也传递到服务提供方,在执行服务提供方的业务逻辑前,把 XID 绑定到当前应用的运行时:

  1. RootContext.bind(rpcXid);

2. 事务的暂停和恢复

在一个全局事务中,如果需要某些业务逻辑不在全局事务的管辖范围内,则在调用前,把 XID 解绑:

  1. String unbindXid = RootContext.unbind();

待相关业务逻辑执行完成,再把 XID 绑定回去,即可实现全局事务的恢复:

  1. RootContext.bind(unbindXid);

4. TCC API

TCC接口定义

  1. public interface NormalTccAction {
  2. /**
  3. * Prepare boolean.
  4. *
  5. * @param a the a
  6. * @param b the b
  7. * @param tccParam the tcc param
  8. * @return the boolean
  9. */
  10. String prepare(int a, List b, TccParam tccParam);
  11. /**
  12. * Commit boolean.
  13. *
  14. * @param actionContext the action context
  15. * @return the boolean
  16. */
  17. boolean commit(BusinessActionContext actionContext, TccParam param);
  18. /**
  19. * Rollback boolean.
  20. *
  21. * @param actionContext the action context
  22. * @return the boolean
  23. */
  24. boolean rollback(BusinessActionContext actionContext, TccParam param);
  25. }

TCC接口定义实现

  1. @LocalTCC
  2. public class NormalTccActionImpl implements NormalTccAction {
  3. @TwoPhaseBusinessAction(name = "tccActionForTest", commitMethod = "commit", rollbackMethod = "rollback", commitArgsClasses = {BusinessActionContext.class, TccParam.class}, rollbackArgsClasses = {BusinessActionContext.class, TccParam.class})
  4. @Override
  5. public String prepare(@BusinessActionContextParameter("a") int a,
  6. @BusinessActionContextParameter(paramName = "b", index = 0) List b,
  7. @BusinessActionContextParameter(isParamInProperty = true) TccParam tccParam) {
  8. return "a";
  9. }
  10. @Override
  11. public boolean commit(BusinessActionContext actionContext,
  12. @BusinessActionContextParameter("tccParam") TccParam param) {
  13. return false;
  14. }
  15. @Override
  16. public boolean rollback(BusinessActionContext actionContext, @BusinessActionContextParameter("tccParam") TccParam param) {
  17. return false;
  18. }
  19. public boolean otherMethod(){
  20. return true;
  21. }
  22. }

TCC API 使用方式

  1. @Test
  2. public void testTcc() {
  3. // 实例化一个未代理的普通TCC接口实现类
  4. NormalTccAction tccAction = new NormalTccActionImpl();
  5. // 通过代理工具ProxyUtil,创建一个代理的TCC接口类
  6. NormalTccAction tccActionProxy = ProxyUtil.createProxy(tccAction);
  7. // 准备一些TCC接口的参数
  8. TccParam tccParam = new TccParam(1, "abc@163.com");
  9. List<String> listB = Arrays.asList("b");
  10. // TCC一阶段提交
  11. String result = tccActionProxy.prepare(0, listB, tccParam);
  12. // 验证
  13. Assertions.assertEquals("a", result);
  14. Assertions.assertNotNull(result);
  15. Assertions.assertEquals("tccActionForTest", branchReference.get());
  16. }

简述说明

  • 1,首先定义TCC接口,prepare,confirm,rollback。
  • 2,实现接口,注意:注解@LocalTCC要修饰在实现类上,注解@TwoPhaseBusinessAction要修饰在实现类方法prepare上,可以通过BusinessActionContext来传递参数。
  • 3,用ProxyUtil.createProxy(T target)创建TCC代理对象。(io.seata.integration.tx.api.util.ProxyUtil)
  • 4,用代理类一阶段提交。

4.1 TCC注解描述

TCC有两个核心注解,分别是TwoPhaseBusinessAction和LocalTCC。

4.1.1 @TwoPhaseBusinessAction

@TwoPhaseBusinessAction表示了当前方法使用TCC模式管理事务提交。

  • name属性,给当前事务注册了一个全局唯一的的TCC bean name。 如代码示例中,name = “TccActionOne”

TCC模式的三个执行阶段分别是:

  • Try 阶段,预定操作资源(Prepare) 这一阶段所以执行的方法便是被@TwoPhaseBusinessAction所修饰的方法。如示例代码中的prepare方法。

  • Confirm 阶段,执行主要业务逻辑(Commit) 这一阶段使用commitMethod属性所指向的方法,来执行Confirm的工作。

  • Cancel 阶段,事务回滚(Rollback) 这一阶段使用rollbackMethod属性所指向的方法,来执行Rollback的工作。

4.1.2 @LocalTCC

@LocalTCC注解用来表示实现了二阶段提交的本地的TCC接口。如果使用Dubbo作为RPC通信组件则无须用此注解。

4.2 重要参数描述

4.2.1 BusinessActionContext

可以使用此入参在TCC模式下,在事务上下文中,传递查询参数。如下属性:

  • xid 全局事务id
  • branchId 分支事务id
  • actionName 分支资源id,(resource id)
  • actionContext 业务传递参数Map,可以通过@BusinessActionContextParameter来标注需要传递的参数。

4.2.2 @BusinessActionContextParameter

用此注解标注需要在事务上下文中传递的参数。被此注解修饰的参数,会被设置在BusinessActionContext中, 可以在commit和rollback阶段中,可以通过BusinessActionContext的getActionContext方法获取传递的业务参数值。 如下:

  1. context.getActionContext("id").toString();